Struct Server 

pub struct Server { /* private fields */ }

A server that is bound and ready to run or spawn, with its options.

Implementations

impl Server

pub fn bind<A, F>(addr: A, app: F) -> Result<Server>

where A: ToSocketAddrs, F: Fn() -> App + Send + Sync + 'static,

Listen on addr ("127.0.0.1:0" picks a free port) with a fresh random token, to serve the apps app makes.

In a session’s own process (Isolation::Processes, the default), this is where the session runs: the process this program started for a browser tab reaches this same call, runs the app for that tab, and exits here, without listening.

Examples found in repository

examples/serve.rs (line 74)

fn main() -> std::io::Result<()> {
    let addr = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "127.0.0.1:8080".to_string());
    rich_web::Server::bind(addr.as_str(), app)?
        .title("rs-rich-web example")
        .run()
}

examples/isolated.rs (line 63)

fn main() -> std::io::Result<()> {
    let mut args = std::env::args().skip(1);
    let mut addr = "127.0.0.1:8080".to_string();
    let mut memory = 256u64 << 20;
    let mut cpu = 10u64;
    let mut token = None;
    let mut startup = None;
    while let Some(arg) = args.next() {
        let mut value = || args.next().expect("a value after the option");
        match arg.as_str() {
            "--memory" => memory = value().parse().expect("bytes"),
            "--cpu" => cpu = value().parse().expect("seconds"),
            "--token" => token = Some(value()),
            "--startup-memory" => startup = Some(value().parse::<usize>().expect("bytes")),
            _ => addr = arg,
        }
    }
    // Startup work in each session's process, before it reaches `bind`.
    if let (Some(bytes), true) = (startup, std::env::var_os(rich_web::SESSION_ENV).is_some()) {
        std::hint::black_box(vec![1u8; bytes]);
    }
    let mut server = rich_web::Server::bind(addr.as_str(), app)?
        .title("isolated sessions")
        .session_memory(memory)
        .session_cpu(Duration::from_secs(cpu));
    if let Some(token) = token {
        server = server.token(token);
    }
    server.run()
}

examples/session_probe.rs (line 85)

fn main() -> std::io::Result<()> {
    let mut args = std::env::args().skip(1);
    let mut addr = "127.0.0.1:8080".to_string();
    let mut token = None;
    let mut startup = None;
    let mut stdin_stop = false;
    let mut nested = false;
    while let Some(arg) = args.next() {
        let mut value = || args.next().expect("a value after the option");
        match arg.as_str() {
            "--token" => token = Some(value()),
            "--startup-sleep" => startup = Some(value().parse::<u64>().expect("ms")),
            "--stdin-stop" => stdin_stop = true,
            "--nested" => nested = true,
            _ => addr = arg,
        }
    }
    if nested {
        // An unrelated program that serves an app: it should get the
        // address it asked for.
        let server = rich_web::Server::bind(addr.as_str(), app)?;
        println!("BOUND {}", server.local_addr());
        return Ok(());
    }
    if let (Some(ms), true) = (startup, std::env::var_os(rich_web::SESSION_ENV).is_some()) {
        std::thread::sleep(Duration::from_millis(ms));
    }
    let mut server = rich_web::Server::bind(addr.as_str(), app)?.title("session probe");
    if let Some(token) = token {
        server = server.token(token);
    }
    if stdin_stop {
        let handle = server.spawn()?;
        println!("Serving session probe at {}", handle.url());
        let mut line = String::new();
        std::io::stdin().lock().read_line(&mut line)?;
        let started = Instant::now();
        handle.stop();
        println!("STOPPED {}", started.elapsed().as_millis());
        return Ok(());
    }
    server.run()
}

pub fn bind_command<A>(addr: A, command: impl Into<Command>) -> Result<Server>

where A: ToSocketAddrs,

Listen on addr with a fresh random token, to run command on a pseudo-terminal of its own for each tab (through LocalPty). The page’s title is the program’s name unless set.

pub fn bind_host<A, F>(addr: A, host: F) -> Result<Server>

where A: ToSocketAddrs, F: Fn() -> Box<dyn PtyHost> + Send + Sync + 'static,

Listen on addr with a fresh random token, to run a program on the PtyHost host makes for each tab: an SSH session, a container’s exec stream, or a test host. It is made, started and dropped on the session’s own thread. max_buffered bounds only what the session holds: a host that reads ahead buffers on its own terms.

pub fn isolation(self, isolation: Isolation) -> Server

Where an app’s sessions run: each in a process of its own (Isolation::Processes, the default), or each on a thread of the server (Isolation::Threads). A program’s sessions (a command, a host) are processes already, and this does not change them.

pub fn session_command<P, I, S>(self, program: P, args: I) -> Server

where P: Into<PathBuf>, I: IntoIterator<Item = S>, S: Into<OsString>,

Start each session’s process as program with args, rather than as this program with the arguments it was given. It must reach the same serve or Server::bind call: an interpreter running the same script, say (Python’s rs_rich.tui.serve passes its own).

pub fn session_memory(self, bytes: u64) -> Server

Cap each session’s process at bytes of memory (its address space): an allocation past it fails, and the process ends, alone. On Linux it holds from the moment the process starts; on other Unix systems from when it reaches serve; macOS has no such limit, and elsewhere (Windows) it is not applied.

Examples found in repository

examples/isolated.rs (line 65)

fn main() -> std::io::Result<()> {
    let mut args = std::env::args().skip(1);
    let mut addr = "127.0.0.1:8080".to_string();
    let mut memory = 256u64 << 20;
    let mut cpu = 10u64;
    let mut token = None;
    let mut startup = None;
    while let Some(arg) = args.next() {
        let mut value = || args.next().expect("a value after the option");
        match arg.as_str() {
            "--memory" => memory = value().parse().expect("bytes"),
            "--cpu" => cpu = value().parse().expect("seconds"),
            "--token" => token = Some(value()),
            "--startup-memory" => startup = Some(value().parse::<usize>().expect("bytes")),
            _ => addr = arg,
        }
    }
    // Startup work in each session's process, before it reaches `bind`.
    if let (Some(bytes), true) = (startup, std::env::var_os(rich_web::SESSION_ENV).is_some()) {
        std::hint::black_box(vec![1u8; bytes]);
    }
    let mut server = rich_web::Server::bind(addr.as_str(), app)?
        .title("isolated sessions")
        .session_memory(memory)
        .session_cpu(Duration::from_secs(cpu));
    if let Some(token) = token {
        server = server.token(token);
    }
    server.run()
}

pub fn session_cpu(self, time: Duration) -> Server

Cap each session’s process at time of CPU (whole seconds, at least one): past it the process is killed, alone. A session that waits for input uses none. On Linux it holds from the moment the process starts; on other Unix systems from when it reaches serve; elsewhere (Windows) it is not applied.

Examples found in repository

examples/isolated.rs (line 66)

fn main() -> std::io::Result<()> {
    let mut args = std::env::args().skip(1);
    let mut addr = "127.0.0.1:8080".to_string();
    let mut memory = 256u64 << 20;
    let mut cpu = 10u64;
    let mut token = None;
    let mut startup = None;
    while let Some(arg) = args.next() {
        let mut value = || args.next().expect("a value after the option");
        match arg.as_str() {
            "--memory" => memory = value().parse().expect("bytes"),
            "--cpu" => cpu = value().parse().expect("seconds"),
            "--token" => token = Some(value()),
            "--startup-memory" => startup = Some(value().parse::<usize>().expect("bytes")),
            _ => addr = arg,
        }
    }
    // Startup work in each session's process, before it reaches `bind`.
    if let (Some(bytes), true) = (startup, std::env::var_os(rich_web::SESSION_ENV).is_some()) {
        std::hint::black_box(vec![1u8; bytes]);
    }
    let mut server = rich_web::Server::bind(addr.as_str(), app)?
        .title("isolated sessions")
        .session_memory(memory)
        .session_cpu(Duration::from_secs(cpu));
    if let Some(token) = token {
        server = server.token(token);
    }
    server.run()
}

pub fn max_sessions(self, n: usize) -> Server

Run at most n sessions at once (8 by default); a browser that opens one more is refused until one ends.

pub fn max_buffered(self, bytes: usize) -> Server

For a program: hold at most about bytes of its output for a page that has not shown it yet (1 MiB by default). Half is output sent and not yet acknowledged by the page, half is output read from the program and not yet sent; past that, the program’s writes wait until the page catches up, as on a slow terminal, so nothing is dropped and memory stays bounded however fast it writes, at any size (a LocalPty with backpressure never drops output, even past its own 16 MiB limit without it). Apps send whole frames and are not affected.

pub fn compress(self, from: Option<usize>) -> Server

Compress frames of from bytes or more with deflate, for pages that can undo it (they have DecompressionStream, and ask with z=1): an app’s frames, the DOM renderer’s messages and a program’s output. Off (None) by default. Worth it over a slow link: measured on a few scenes, frames shrink to 5 to 30% of their size for 15 to 60 µs each (level 1). On a local machine it only adds work. 1024 is a fair threshold.

pub fn renderer(self, renderer: Renderer) -> Server

How an app’s page draws it: Renderer::Xterm (the default) or Renderer::Dom. A page’s address can ask for either with &renderer=xterm or &renderer=dom. A program is always drawn by xterm.js.

pub fn token(self, token: impl Into<String>) -> Server

Use token instead of a random one, for an address that stays the same between runs. Keep it as secret, and as long: anyone with it can use the app.

Panics

When token is empty or has characters other than ASCII letters, digits, -, _, . and ~ (it goes in a URL as it is).

Examples found in repository

examples/isolated.rs (line 68)

fn main() -> std::io::Result<()> {
    let mut args = std::env::args().skip(1);
    let mut addr = "127.0.0.1:8080".to_string();
    let mut memory = 256u64 << 20;
    let mut cpu = 10u64;
    let mut token = None;
    let mut startup = None;
    while let Some(arg) = args.next() {
        let mut value = || args.next().expect("a value after the option");
        match arg.as_str() {
            "--memory" => memory = value().parse().expect("bytes"),
            "--cpu" => cpu = value().parse().expect("seconds"),
            "--token" => token = Some(value()),
            "--startup-memory" => startup = Some(value().parse::<usize>().expect("bytes")),
            _ => addr = arg,
        }
    }
    // Startup work in each session's process, before it reaches `bind`.
    if let (Some(bytes), true) = (startup, std::env::var_os(rich_web::SESSION_ENV).is_some()) {
        std::hint::black_box(vec![1u8; bytes]);
    }
    let mut server = rich_web::Server::bind(addr.as_str(), app)?
        .title("isolated sessions")
        .session_memory(memory)
        .session_cpu(Duration::from_secs(cpu));
    if let Some(token) = token {
        server = server.token(token);
    }
    server.run()
}

examples/session_probe.rs (line 94)

fn main() -> std::io::Result<()> {
    let mut args = std::env::args().skip(1);
    let mut addr = "127.0.0.1:8080".to_string();
    let mut token = None;
    let mut startup = None;
    let mut stdin_stop = false;
    let mut nested = false;
    while let Some(arg) = args.next() {
        let mut value = || args.next().expect("a value after the option");
        match arg.as_str() {
            "--token" => token = Some(value()),
            "--startup-sleep" => startup = Some(value().parse::<u64>().expect("ms")),
            "--stdin-stop" => stdin_stop = true,
            "--nested" => nested = true,
            _ => addr = arg,
        }
    }
    if nested {
        // An unrelated program that serves an app: it should get the
        // address it asked for.
        let server = rich_web::Server::bind(addr.as_str(), app)?;
        println!("BOUND {}", server.local_addr());
        return Ok(());
    }
    if let (Some(ms), true) = (startup, std::env::var_os(rich_web::SESSION_ENV).is_some()) {
        std::thread::sleep(Duration::from_millis(ms));
    }
    let mut server = rich_web::Server::bind(addr.as_str(), app)?.title("session probe");
    if let Some(token) = token {
        server = server.token(token);
    }
    if stdin_stop {
        let handle = server.spawn()?;
        println!("Serving session probe at {}", handle.url());
        let mut line = String::new();
        std::io::stdin().lock().read_line(&mut line)?;
        let started = Instant::now();
        handle.stop();
        println!("STOPPED {}", started.elapsed().as_millis());
        return Ok(());
    }
    server.run()
}

pub fn allow_host(self, host: impl AsRef<str>) -> Server

Also answer to host (say "box.lan", or "box.lan:9000"): a name this machine is reached by that the server does not know itself. The server’s port is added unless host names one. The Host of a WebSocket upgrade must be one the server answers to: its bound address (with localhost for a loopback one), or, bound to all interfaces, the loopback addresses, localhost, this machine’s own name and the address the connection arrived on; plus these. That is what stops a page whose name was pointed here (DNS rebinding). The token is still required.

pub fn allow_origin(self, origin: impl Into<String>) -> Server

Also accept WebSocket upgrades from pages served at origin (say "https://term.example.com"): the address a reverse proxy serves this server’s page from. The token is still required.

pub fn title(self, title: impl Into<String>) -> Server

The page’s title (intuiTUIve for an app, the program’s name for a command, by default).

Examples found in repository

examples/serve.rs (line 75)

fn main() -> std::io::Result<()> {
    let addr = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "127.0.0.1:8080".to_string());
    rich_web::Server::bind(addr.as_str(), app)?
        .title("rs-rich-web example")
        .run()
}

examples/isolated.rs (line 64)

fn main() -> std::io::Result<()> {
    let mut args = std::env::args().skip(1);
    let mut addr = "127.0.0.1:8080".to_string();
    let mut memory = 256u64 << 20;
    let mut cpu = 10u64;
    let mut token = None;
    let mut startup = None;
    while let Some(arg) = args.next() {
        let mut value = || args.next().expect("a value after the option");
        match arg.as_str() {
            "--memory" => memory = value().parse().expect("bytes"),
            "--cpu" => cpu = value().parse().expect("seconds"),
            "--token" => token = Some(value()),
            "--startup-memory" => startup = Some(value().parse::<usize>().expect("bytes")),
            _ => addr = arg,
        }
    }
    // Startup work in each session's process, before it reaches `bind`.
    if let (Some(bytes), true) = (startup, std::env::var_os(rich_web::SESSION_ENV).is_some()) {
        std::hint::black_box(vec![1u8; bytes]);
    }
    let mut server = rich_web::Server::bind(addr.as_str(), app)?
        .title("isolated sessions")
        .session_memory(memory)
        .session_cpu(Duration::from_secs(cpu));
    if let Some(token) = token {
        server = server.token(token);
    }
    server.run()
}

examples/session_probe.rs (line 92)

fn main() -> std::io::Result<()> {
    let mut args = std::env::args().skip(1);
    let mut addr = "127.0.0.1:8080".to_string();
    let mut token = None;
    let mut startup = None;
    let mut stdin_stop = false;
    let mut nested = false;
    while let Some(arg) = args.next() {
        let mut value = || args.next().expect("a value after the option");
        match arg.as_str() {
            "--token" => token = Some(value()),
            "--startup-sleep" => startup = Some(value().parse::<u64>().expect("ms")),
            "--stdin-stop" => stdin_stop = true,
            "--nested" => nested = true,
            _ => addr = arg,
        }
    }
    if nested {
        // An unrelated program that serves an app: it should get the
        // address it asked for.
        let server = rich_web::Server::bind(addr.as_str(), app)?;
        println!("BOUND {}", server.local_addr());
        return Ok(());
    }
    if let (Some(ms), true) = (startup, std::env::var_os(rich_web::SESSION_ENV).is_some()) {
        std::thread::sleep(Duration::from_millis(ms));
    }
    let mut server = rich_web::Server::bind(addr.as_str(), app)?.title("session probe");
    if let Some(token) = token {
        server = server.token(token);
    }
    if stdin_stop {
        let handle = server.spawn()?;
        println!("Serving session probe at {}", handle.url());
        let mut line = String::new();
        std::io::stdin().lock().read_line(&mut line)?;
        let started = Instant::now();
        handle.stop();
        println!("STOPPED {}", started.elapsed().as_millis());
        return Ok(());
    }
    server.run()
}

pub fn local_addr(&self) -> SocketAddr

The address the server listens on.

Examples found in repository

examples/session_probe.rs (line 86)

fn main() -> std::io::Result<()> {
    let mut args = std::env::args().skip(1);
    let mut addr = "127.0.0.1:8080".to_string();
    let mut token = None;
    let mut startup = None;
    let mut stdin_stop = false;
    let mut nested = false;
    while let Some(arg) = args.next() {
        let mut value = || args.next().expect("a value after the option");
        match arg.as_str() {
            "--token" => token = Some(value()),
            "--startup-sleep" => startup = Some(value().parse::<u64>().expect("ms")),
            "--stdin-stop" => stdin_stop = true,
            "--nested" => nested = true,
            _ => addr = arg,
        }
    }
    if nested {
        // An unrelated program that serves an app: it should get the
        // address it asked for.
        let server = rich_web::Server::bind(addr.as_str(), app)?;
        println!("BOUND {}", server.local_addr());
        return Ok(());
    }
    if let (Some(ms), true) = (startup, std::env::var_os(rich_web::SESSION_ENV).is_some()) {
        std::thread::sleep(Duration::from_millis(ms));
    }
    let mut server = rich_web::Server::bind(addr.as_str(), app)?.title("session probe");
    if let Some(token) = token {
        server = server.token(token);
    }
    if stdin_stop {
        let handle = server.spawn()?;
        println!("Serving session probe at {}", handle.url());
        let mut line = String::new();
        std::io::stdin().lock().read_line(&mut line)?;
        let started = Instant::now();
        handle.stop();
        println!("STOPPED {}", started.elapsed().as_millis());
        return Ok(());
    }
    server.run()
}

pub fn access_token(&self) -> &str

The token browsers must give.

pub fn url(&self) -> String

The address to open in a browser, with the token.

pub fn run(self) -> Result<()>

Print the URL (and a warning when the address is not loopback), then serve until the process ends.

Examples found in repository

examples/serve.rs (line 76)

fn main() -> std::io::Result<()> {
    let addr = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "127.0.0.1:8080".to_string());
    rich_web::Server::bind(addr.as_str(), app)?
        .title("rs-rich-web example")
        .run()
}

examples/isolated.rs (line 70)

fn main() -> std::io::Result<()> {
    let mut args = std::env::args().skip(1);
    let mut addr = "127.0.0.1:8080".to_string();
    let mut memory = 256u64 << 20;
    let mut cpu = 10u64;
    let mut token = None;
    let mut startup = None;
    while let Some(arg) = args.next() {
        let mut value = || args.next().expect("a value after the option");
        match arg.as_str() {
            "--memory" => memory = value().parse().expect("bytes"),
            "--cpu" => cpu = value().parse().expect("seconds"),
            "--token" => token = Some(value()),
            "--startup-memory" => startup = Some(value().parse::<usize>().expect("bytes")),
            _ => addr = arg,
        }
    }
    // Startup work in each session's process, before it reaches `bind`.
    if let (Some(bytes), true) = (startup, std::env::var_os(rich_web::SESSION_ENV).is_some()) {
        std::hint::black_box(vec![1u8; bytes]);
    }
    let mut server = rich_web::Server::bind(addr.as_str(), app)?
        .title("isolated sessions")
        .session_memory(memory)
        .session_cpu(Duration::from_secs(cpu));
    if let Some(token) = token {
        server = server.token(token);
    }
    server.run()
}

examples/session_probe.rs (line 106)

fn main() -> std::io::Result<()> {
    let mut args = std::env::args().skip(1);
    let mut addr = "127.0.0.1:8080".to_string();
    let mut token = None;
    let mut startup = None;
    let mut stdin_stop = false;
    let mut nested = false;
    while let Some(arg) = args.next() {
        let mut value = || args.next().expect("a value after the option");
        match arg.as_str() {
            "--token" => token = Some(value()),
            "--startup-sleep" => startup = Some(value().parse::<u64>().expect("ms")),
            "--stdin-stop" => stdin_stop = true,
            "--nested" => nested = true,
            _ => addr = arg,
        }
    }
    if nested {
        // An unrelated program that serves an app: it should get the
        // address it asked for.
        let server = rich_web::Server::bind(addr.as_str(), app)?;
        println!("BOUND {}", server.local_addr());
        return Ok(());
    }
    if let (Some(ms), true) = (startup, std::env::var_os(rich_web::SESSION_ENV).is_some()) {
        std::thread::sleep(Duration::from_millis(ms));
    }
    let mut server = rich_web::Server::bind(addr.as_str(), app)?.title("session probe");
    if let Some(token) = token {
        server = server.token(token);
    }
    if stdin_stop {
        let handle = server.spawn()?;
        println!("Serving session probe at {}", handle.url());
        let mut line = String::new();
        std::io::stdin().lock().read_line(&mut line)?;
        let started = Instant::now();
        handle.stop();
        println!("STOPPED {}", started.elapsed().as_millis());
        return Ok(());
    }
    server.run()
}

pub fn run_until(self, until: impl FnOnce()) -> Result<()>

Print the URL as run does, then serve until until returns, and stop as Handle::stop does: every session ends, and this returns once their programs have. until runs on this thread: a wait for a signal, say, as rich serve waits for Ctrl+C, so that no program outlives the server.

pub fn spawn(self) -> Result<Handle>

Serve on a thread of its own, printing nothing, until the Handle is stopped or dropped.

Examples found in repository

examples/session_probe.rs (line 97)

fn main() -> std::io::Result<()> {
    let mut args = std::env::args().skip(1);
    let mut addr = "127.0.0.1:8080".to_string();
    let mut token = None;
    let mut startup = None;
    let mut stdin_stop = false;
    let mut nested = false;
    while let Some(arg) = args.next() {
        let mut value = || args.next().expect("a value after the option");
        match arg.as_str() {
            "--token" => token = Some(value()),
            "--startup-sleep" => startup = Some(value().parse::<u64>().expect("ms")),
            "--stdin-stop" => stdin_stop = true,
            "--nested" => nested = true,
            _ => addr = arg,
        }
    }
    if nested {
        // An unrelated program that serves an app: it should get the
        // address it asked for.
        let server = rich_web::Server::bind(addr.as_str(), app)?;
        println!("BOUND {}", server.local_addr());
        return Ok(());
    }
    if let (Some(ms), true) = (startup, std::env::var_os(rich_web::SESSION_ENV).is_some()) {
        std::thread::sleep(Duration::from_millis(ms));
    }
    let mut server = rich_web::Server::bind(addr.as_str(), app)?.title("session probe");
    if let Some(token) = token {
        server = server.token(token);
    }
    if stdin_stop {
        let handle = server.spawn()?;
        println!("Serving session probe at {}", handle.url());
        let mut line = String::new();
        std::io::stdin().lock().read_line(&mut line)?;
        let started = Instant::now();
        handle.stop();
        println!("STOPPED {}", started.elapsed().as_millis());
        return Ok(());
    }
    server.run()
}