1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345
//! A middleware for browser reloading, built on top of [`tower`].
//!
//! # Example
//!
//! Note that [`axum`] is only used as an example here, pretty much any Rust
//! HTTP library or framework will be compatible!
//!
//! ```
//! use axum::{response::Html, routing::get, Router};
//! use tower_livereload::LiveReloadLayer;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let app = Router::new()
//! .route("/", get(|| async { Html("<h1>Wow, such webdev</h1>") }))
//! .layer(LiveReloadLayer::new());
//!
//! let listener = tokio::net::TcpListener::bind("0.0.0.0:3030").await?;
//! axum::serve(listener, app).await?;
//!
//! Ok(())
//! }
//! ```
//!
//! If you continuously rebuild and rerun this example e.g. using [`watchexec`],
//! you should see your browser reload whenever the code is changed.
//!
//! More examples can be found on GitHub under [examples].
//!
//! [`axum`]: https://docs.rs/axum
//! [`tower`]: https://docs.rs/tower
//! [`watchexec`]: https://watchexec.github.io/
//! [examples]: https://github.com/leotaku/tower-livereload/tree/master/examples
//!
//! # Manual reload
//!
//! With the [`Reloader`] utility, it is possible to reload your web browser
//! entirely using hooks from Rust code. See this [example] on GitHub for
//! pointers on how to implement a self-contained live-reloading static server.
//!
//! [example]: https://github.com/leotaku/tower-livereload/blob/master/examples/axum-file-watch/
//!
//! # Ecosystem compatibility
//!
//! `tower-livereload` has been built from the ground up to provide the highest
//! amount of ecosystem compatibility.
//!
//! The provided middleware uses the [`http`] and [`http_body`] crates as its
//! HTTP abstractions. That means it is compatible with any library or framework
//! that also uses those crates, such as [`hyper`], [`axum`], [`tonic`], and
//! [`warp`].
//!
//! [`http`]: https://docs.rs/http
//! [`http_body`]: https://docs.rs/http_body
//! [`hyper`]: https://docs.rs/hyper
//! [`axum`]: https://docs.rs/axum
//! [`tonic`]: https://docs.rs/tonic
//! [`warp`]: https://docs.rs/warp
//!
//! # Heuristics
//!
//! To provide LiveReload functionality, we have to inject code into HTML web
//! pages. To determine whether a page is injectable, some header-based
//! heuristics are used. In particular, [`Content-Type`] has to start with
//! `text/html`, [`Content-Length`] must be set, and [`Content-Encoding`] must
//! not be set.
//!
//! If LiveReload is not working for some of your pages, ensure that these
//! heuristics apply to your responses. In particular, if you use middleware to
//! compress your HTML, ensure that the [`LiveReload`] middleware is
//! applied before your compression middleware.
//!
//! [`Content-Type`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
//! [`Content-Length`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Length
//! [`Content-Encoding`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding
#![forbid(unsafe_code, unused_unsafe)]
#![warn(clippy::all, missing_docs, nonstandard_style, future_incompatible)]
#![allow(clippy::type_complexity)]
mod inject;
mod long_poll;
mod overlay;
pub mod predicate;
mod ready_polyfill;
use std::{convert::Infallible, time::Duration};
use http::{header, Request, Response, StatusCode};
use inject::InjectService;
use long_poll::LongPollBody;
use overlay::OverlayService;
use predicate::{Always, ContentTypeStartsWith, Predicate};
use tokio::sync::broadcast::Sender;
use tower::{Layer, Service};
const DEFAULT_PREFIX: &str = "/tower-livereload/long-name-to-avoid-collisions";
/// Utility to send reload requests to clients.
#[derive(Clone, Debug)]
pub struct Reloader {
sender: Sender<()>,
}
impl Reloader {
/// Create a new [`Reloader`].
///
/// This can be manually passed to the [`LiveReload`] constructor, but in
/// most cases the [`LiveReloadLayer`] and [`LiveReloadLayer::reloader`]
/// utilities are preferred.
pub fn new() -> Self {
let (sender, _) = tokio::sync::broadcast::channel(1);
Self { sender }
}
/// Send a reload request to all open clients.
pub fn reload(&self) {
self.sender.send(()).ok();
}
}
impl Default for Reloader {
fn default() -> Self {
Self::new()
}
}
/// Layer to apply [`LiveReload`] middleware.
#[derive(Clone, Debug)]
pub struct LiveReloadLayer<ReqPred = Always, ResPred = ContentTypeStartsWith<&'static str>> {
custom_prefix: Option<String>,
reloader: Reloader,
req_predicate: ReqPred,
res_predicate: ResPred,
reload_interval: Duration,
}
impl LiveReloadLayer {
/// Create a new [`LiveReloadLayer`] with the default prefix for internal
/// routes.
///
/// The default prefix is deliberately long and specific to avoid any
/// accidental collisions with the wrapped service.
pub fn new() -> Self {
Self {
custom_prefix: None,
reloader: Reloader::new(),
req_predicate: Always,
res_predicate: ContentTypeStartsWith::new("text/html"),
reload_interval: Duration::from_secs(1),
}
}
/// Create a new [`LiveReloadLayer`] with a custom prefix.
#[deprecated(
since = "0.8.0",
note = "please use `LiveReloadLayer::new` and `custom_prefix` instead"
)]
pub fn with_custom_prefix<P: Into<String>>(prefix: P) -> Self {
Self::new().custom_prefix(prefix)
}
}
impl<ReqPred, ResPred> LiveReloadLayer<ReqPred, ResPred> {
/// Set a custom prefix for internal routes for the given
/// [`LiveReloadLayer`].
pub fn custom_prefix<P: Into<String>>(self, prefix: P) -> Self {
Self {
custom_prefix: Some(prefix.into()),
..self
}
}
/// Set a custom predicate for requests that should have their response HTML
/// injected with live-reload logic.
///
/// Note that this predicate is applied in addition to the default response
/// predicate, which makes sure that only HTML responses are injected.
///
/// Also see [`predicate`] for pre-defined predicates and
/// [`predicate::Predicate`] for how to implement your own predicates.
pub fn request_predicate<Body, P: Predicate<Request<Body>>>(
self,
predicate: P,
) -> LiveReloadLayer<P, ResPred> {
LiveReloadLayer {
custom_prefix: self.custom_prefix,
reloader: self.reloader,
req_predicate: predicate,
res_predicate: self.res_predicate,
reload_interval: self.reload_interval,
}
}
/// Set a custom predicate for responses that should be injected with
/// live-reload logic.
///
/// Note that this predicate is applied instead of the default response
/// predicate, which would make sure that only HTML responses are injected.
/// However, even with a custom predicate only responses that have a valid
/// [`Content-Length`] header, and no [`Content-Encoding`] header can and
/// will be injected.
///
/// Also see [`predicate`] for pre-defined predicates and
/// [`predicate::Predicate`] for how to implement your own predicates.
///
/// [`Content-Length`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Length
/// [`Content-Encoding`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding
pub fn response_predicate<Body, P: Predicate<Response<Body>>>(
self,
predicate: P,
) -> LiveReloadLayer<ReqPred, P> {
LiveReloadLayer {
custom_prefix: self.custom_prefix,
reloader: self.reloader,
req_predicate: self.req_predicate,
res_predicate: predicate,
reload_interval: self.reload_interval,
}
}
/// Set a custom retry interval for the live-reload logic.
pub fn reload_interval(self, interval: Duration) -> Self {
Self {
reload_interval: interval,
..self
}
}
/// Return a manual [`Reloader`] trigger for the given [`LiveReloadLayer`].
pub fn reloader(&self) -> Reloader {
self.reloader.clone()
}
}
impl Default for LiveReloadLayer {
fn default() -> Self {
Self::new()
}
}
impl<S, ReqPred: Copy, ResPred: Copy> Layer<S> for LiveReloadLayer<ReqPred, ResPred> {
type Service = LiveReload<S, ReqPred, ResPred>;
fn layer(&self, inner: S) -> Self::Service {
#[allow(deprecated)]
LiveReload::new(
inner,
self.reloader.clone(),
self.req_predicate,
self.res_predicate,
self.reload_interval,
self.custom_prefix
.as_ref()
.cloned()
.unwrap_or_else(|| DEFAULT_PREFIX.to_owned()),
)
}
}
type InnerService<S, ReqPred, ResPred> = OverlayService<
String,
Infallible,
OverlayService<LongPollBody, Infallible, InjectService<S, ReqPred, ResPred>>,
>;
/// Middleware to enable LiveReload functionality.
#[derive(Clone, Debug)]
pub struct LiveReload<S, ReqPred = Always, ResPred = ContentTypeStartsWith<&'static str>> {
service: InnerService<S, ReqPred, ResPred>,
}
impl<S, ReqPred, ResPred> LiveReload<S, ReqPred, ResPred> {
#[deprecated(
since = "0.9.0",
note = "please use `LiveReloadLayer::new().layer(service)` instead"
)]
/// Create a new [`LiveReload`] middleware.
pub fn new<P: Into<String>>(
service: S,
reloader: Reloader,
req_predicate: ReqPred,
res_predicate: ResPred,
reload_interval: Duration,
prefix: P,
) -> Self {
let prefix = prefix.into();
let long_poll_path = format!("{}/long-poll", prefix);
let back_up_path = format!("{}/back-up", prefix);
let inject = InjectService::new(
service,
format!(
include_str!("../assets/polling.html"),
long_poll = long_poll_path,
back_up = back_up_path,
reload_interval = reload_interval.as_millis(),
)
.into(),
req_predicate,
res_predicate,
);
let overlay_poll = OverlayService::new(inject).path(long_poll_path, move || {
Response::builder()
.status(StatusCode::OK)
.header(header::CONTENT_TYPE, "text/event-stream")
.body(LongPollBody::new(reloader.sender.subscribe()))
.map_err(|_| unreachable!())
});
let overlay_up = OverlayService::new(overlay_poll).path(back_up_path, || {
Response::builder()
.status(StatusCode::OK)
.header(header::CONTENT_TYPE, "text/plain")
.body("Ok".to_owned())
.map_err(|_| unreachable!())
});
LiveReload {
service: overlay_up,
}
}
}
impl<ReqBody, ResBody, S, ReqPred, ResPred> Service<Request<ReqBody>>
for LiveReload<S, ReqPred, ResPred>
where
S: Service<Request<ReqBody>, Response = Response<ResBody>>,
ResBody: http_body::Body,
ReqPred: Predicate<Request<ReqBody>>,
ResPred: Predicate<Response<ResBody>>,
{
type Response = <InnerService<S, ReqPred, ResPred> as Service<Request<ReqBody>>>::Response;
type Error = <InnerService<S, ReqPred, ResPred> as Service<Request<ReqBody>>>::Error;
type Future = <InnerService<S, ReqPred, ResPred> as Service<Request<ReqBody>>>::Future;
fn poll_ready(
&mut self,
cx: &mut std::task::Context<'_>,
) -> std::task::Poll<Result<(), Self::Error>> {
self.service.poll_ready(cx)
}
fn call(&mut self, req: Request<ReqBody>) -> Self::Future {
self.service.call(req)
}
}