Expand description
Penguin is a dev server with features like auto-reloading, a static file server, and proxy-support. It is available both, as an app and as a library. You are currently reading the library docs. If you are interested in the CLI app, see the README.
This library essentially allows you to configure and then start an HTTP
server. After starting the server you get a Controller
which allows you
to send commands to active browser sessions, like reloading the page or
showing a message.
Quick start
This should get you started as it shows almost everything this library has to offer:
use std::{path::Path, time::Duration};
use penguin::Server;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Configure the server.
let (server, controller) = Server::bind(([127, 0, 0, 1], 4090).into())
.proxy("localhost:8000".parse()?)
.add_mount("/assets", Path::new("./frontend/build"))?
.build()?;
// In some other task, you can control the browser sessions. This dummy
// code just waits 5 seconds and then reloads all sessions.
tokio::spawn(async move {
tokio::time::sleep(Duration::from_secs(5)).await;
controller.reload();
});
server.await?;
Ok(())
}
Routing
Incoming requests are routed like this (from highest to lowest priority):
- Requests to the control path (
/~~penguin
by default) are internally handled. This is used for establishing WS connections and to receive commands. - Requests with a path matching one of the mounts is served from that
directory.
- The most specific mount (i.e. the one with the longest URI path) is
used. Consider there are two mounts:
/cat
->./foo
and/cat/paw
->./bar
. Then a request to/cat/paw/info.json
is replied to with./bar/info.json
while a request to/cat/style.css
is replied to with./foo/style.css
- The most specific mount (i.e. the one with the longest URI path) is
used. Consider there are two mounts:
- If a proxy is configured, then all remaining requests are forwarded to it and its reply is forwarded back to the initiator of the request. Otherwise (no proxy configured), all remaining requests are answered with 404.
Re-exports
pub extern crate hyper;
Modules
- Utility functions.
Structs
- Builder for the configuration of
Server
. - A valid penguin server configuration.
- A handle to send commands to the server.
- A mapping from URI path to file system path.
- Defintion of a proxy target consisting of a scheme and authority (≈host).
- Penguin server: the main type of this library.
Enums
- Configuration validation error.
- Error that can occur when parsing a
ProxyTarget
from a string.
Constants
- The URI path which is used for penguin internal control functions (e.g. opening WS connections).