vorma 0.86.0-pre.6

//! The build output that `vorma build` or `vorma dev` writes into the build
//! directory: the build metadata and the published static public assets.
//!
//! In production the build never changes. In development, `vorma dev`
//! republishes the metadata, and a request that starts after a publication
//! uses the new build from start to finish.

use std::collections::{BTreeMap, HashMap};
use std::fmt;
use std::path::{Path, PathBuf};
use std::sync::Arc;

use primitives_rs::http::csp::csp_sha256_hash_source;
use serde::Deserialize;
use tokio::sync::Mutex;

/// The format of `metadata.json`. The server refuses a file of another
/// format. The `vorma` package writes the same number as `formatVersion`, in
/// `BUILD_METADATA_FORMAT_VERSION`.
pub const BUILD_METADATA_FORMAT_VERSION: u32 = 1;

/// One browser module's build-to-runtime projection. A view module's default
/// export is its view. The metadata leaves out a list that is empty.
#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub(crate) struct ClientModule {
	pub(crate) import_url: String,
	#[serde(default)]
	pub(crate) dep_urls: Vec<String>,
	#[serde(default)]
	pub(crate) css_bundle_urls: Vec<String>,
	/// The static public assets that the module's JavaScript references. A page
	/// preloads the images and fonts among them.
	#[serde(default)]
	pub(crate) referenced_static_public_asset_urls: Vec<String>,
}

#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub(crate) enum RuntimeMode {
	Prod,
	Dev,
}

/// Everything one build determines about its own output.
#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub(crate) struct BuildMetadata {
	pub(crate) client_build_id: String,
	/// The hash of the declarations that the build read from the server
	/// binary.
	pub(crate) declarations_hash: String,
	pub(crate) runtime_mode: RuntimeMode,
	/// The URL path under which the server serves the files of the build
	/// directory's `public` directory, such as `/` or `/static/`.
	pub(crate) static_public_assets_serve_url_path_prefix: String,
	/// The names of exactly the files in the build directory's `public`
	/// directory. Every file is content-hashed, so the server serves each as
	/// immutable.
	pub(crate) static_public_asset_file_names: Vec<String>,
	/// Each static public asset's source key and its published URL path.
	pub(crate) static_public_asset_urls: HashMap<String, String>,
	pub(crate) critical_css: String,
	/// The development HTML that Vite's plugins add to the head; absent from
	/// production metadata.
	pub(crate) dev_head_html: Option<String>,
	/// The development HTML that Vite's plugins add to the start of the body;
	/// absent from production metadata.
	pub(crate) dev_body_prepend_html: Option<String>,
	/// The development HTML that Vite's plugins add to the end of the body;
	/// absent from production metadata.
	pub(crate) dev_body_html: Option<String>,
	/// What the Content-Security-Policy needs from `vorma dev`; absent from
	/// production metadata.
	pub(crate) dev_csp: Option<DevCsp>,
	pub(crate) client_entry: ClientModule,
	/// Each view's module, by the pattern that the view states.
	pub(crate) client_views: BTreeMap<String, ClientModule>,
}

/// The development session's values that only `vorma dev` knows.
#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub(crate) struct DevCsp {
	/// The origin from which pages load browser modules, styles, images, and
	/// fonts, such as `http://127.0.0.1:5173`.
	pub(crate) module_server_origin: String,
	/// The origin of the module server's WebSocket, such as
	/// `ws://127.0.0.1:5173`.
	pub(crate) web_socket_origin: String,
	/// The value of Vite's `html.cspNonce`, which `vorma dev` chooses unless the
	/// application sets it.
	pub(crate) nonce: Option<String>,
}

/// Each static public asset's published URL by its source file name.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct StaticPublicAssets(HashMap<String, String>);

impl StaticPublicAssets {
	/// Returns the published URL of a file in the static public asset source
	/// directory, such as `"favicon.svg"`.
	pub fn get(&self, src_file_name: &str) -> Option<&str> {
		self.0.get(src_file_name).map(String::as_str)
	}
}

/// Builds the assets from pairs of a source file name and a published URL,
/// for example in a test that calls a handler directly.
impl<Name: Into<String>, Url: Into<String>, const COUNT: usize> From<[(Name, Url); COUNT]>
	for StaticPublicAssets
{
	fn from(pairs: [(Name, Url); COUNT]) -> Self {
		pairs.into_iter().collect()
	}
}

impl<Name: Into<String>, Url: Into<String>> FromIterator<(Name, Url)> for StaticPublicAssets {
	fn from_iter<Pairs: IntoIterator<Item = (Name, Url)>>(pairs: Pairs) -> Self {
		Self(
			pairs
				.into_iter()
				.map(|(name, url)| (name.into(), url.into()))
				.collect(),
		)
	}
}

/// The stand-in for a client build that [`App::load_for_tests`](crate::App::load_for_tests)
/// loads, so that a test can send requests to the application's service
/// without running `vorma build`.
///
/// The stand-in is a production build that exists only in memory. It has no
/// client views, no critical CSS, and no files, and its client entry module
/// does not exist.
#[derive(Clone, Debug)]
pub struct TestBuild {
	/// The build's ID, which handlers read as `latest_known_client_build_id`
	/// and which a request's client build ID is compared with. It must be a
	/// valid header value and must not be empty.
	pub client_build_id: String,
	/// The published URL of each static public asset by its source file name,
	/// which handlers read as `static_public_assets`. The service serves no
	/// file for these URLs.
	pub static_public_assets: StaticPublicAssets,
}

impl TestBuild {
	/// The metadata of the stand-in build, built for the declarations with
	/// this hash.
	pub(crate) fn into_metadata(self, declarations_hash: String) -> BuildMetadata {
		BuildMetadata {
			client_build_id: self.client_build_id,
			declarations_hash,
			runtime_mode: RuntimeMode::Prod,
			static_public_assets_serve_url_path_prefix: "/".to_owned(),
			static_public_asset_file_names: Vec::new(),
			static_public_asset_urls: self.static_public_assets.0,
			critical_css: String::new(),
			dev_head_html: None,
			dev_body_prepend_html: None,
			dev_body_html: None,
			dev_csp: None,
			client_entry: ClientModule {
				import_url: "/vorma-test-build-client-entry.js".to_owned(),
				dep_urls: Vec::new(),
				css_bundle_urls: Vec::new(),
				referenced_static_public_asset_urls: Vec::new(),
			},
			client_views: BTreeMap::new(),
		}
	}
}

/// For each Content-Security-Policy directive, every source that Vorma's own
/// content needs. Each source is complete and quoted where CSP requires it,
/// such as `'self'`, `'sha256-…'`, or `http://127.0.0.1:5173`, so an
/// application can put a list into its directive as it is. A directive that
/// Vorma's content does not use has an empty list.
///
/// The lists are the same for every request of one build or development
/// session. The only nonce is the development session's, described below.
///
/// In production:
///
/// - `script_src` holds `'self'`, for the browser modules that pages load.
/// - `style_src` holds `'self'`, for the stylesheets that pages load, and the
///   hash of the critical CSS that pages inline.
/// - `connect_src` holds `'self'`, for the navigation and endpoint requests
///   that the browser client makes.
/// - `img_src` and `font_src` hold `'self'`, for the files that built
///   stylesheets reference.
/// - `worker_src` is empty.
///
/// Under `vorma dev`, the lists also hold the module server's origin in
/// `script_src`, `style_src`, `img_src`, and `font_src`; the module server's
/// WebSocket origin in `connect_src`; `blob:` in `worker_src`, for Vite's
/// reconnect worker; the hashes of the development head's inline content; and
/// the nonce of Vite's `html.cspNonce` in `script_src` and `style_src`.
/// `vorma dev` chooses a random nonce for each session and sets it as
/// `html.cspNonce` on its Vite server, so a strict `style-src` admits the live
/// critical CSS update with no Vite setting. An `html.cspNonce` in the
/// application's Vite configuration replaces it. Production lists hold no
/// nonce.
///
/// An endpoint call has no inline content, so the middleware context of an
/// endpoint call holds empty lists.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct CspSources {
	/// Sources for `script-src`.
	pub script_src: Vec<String>,
	/// Sources for `style-src`.
	pub style_src: Vec<String>,
	/// Sources for `connect-src`.
	pub connect_src: Vec<String>,
	/// Sources for `img-src`.
	pub img_src: Vec<String>,
	/// Sources for `font-src`.
	pub font_src: Vec<String>,
	/// Sources for `worker-src`.
	pub worker_src: Vec<String>,
}

/// One build's metadata with the values that every request served from it
/// uses.
#[derive(Debug)]
pub(crate) struct BuildSnapshot {
	pub(crate) metadata: BuildMetadata,
	/// The name of each file in the build directory's `public` directory, by
	/// the URL path at which the server serves the file.
	pub(crate) static_public_asset_file_names_by_url: HashMap<String, String>,
	pub(crate) static_public_assets: Arc<StaticPublicAssets>,
	/// The sources that a page response needs for Vorma's own content.
	pub(crate) page_csp_sources: Arc<CspSources>,
}

fn to_csp_hash(content: &str) -> String {
	format!("'{}'", csp_sha256_hash_source(content.as_bytes()))
}

impl BuildSnapshot {
	pub(crate) fn new(metadata: BuildMetadata) -> Self {
		Self {
			static_public_asset_file_names_by_url: metadata
				.static_public_asset_file_names
				.iter()
				.map(|file_name| {
					let url = to_published_file_url(
						&metadata.static_public_assets_serve_url_path_prefix,
						file_name,
					);
					(url, file_name.clone())
				})
				.collect(),
			static_public_assets: Arc::new(StaticPublicAssets(
				metadata.static_public_asset_urls.clone(),
			)),
			page_csp_sources: Arc::new(read_csp_sources(&metadata)),
			metadata,
		}
	}
}

/// The URL path of a published file: the prefix, then each path segment of
/// the file name, percent-encoded as JavaScript's `encodeURIComponent` encodes
/// it. The `vorma` package makes the URL of a published file in the same way.
fn to_published_file_url(serve_url_path_prefix: &str, file_name: &str) -> String {
	let mut url = serve_url_path_prefix.to_owned();
	for byte in file_name.bytes() {
		if byte == b'/' || byte.is_ascii_alphanumeric() || b"-_.!~*'()".contains(&byte) {
			url.push(char::from(byte));
		} else {
			url.push_str(&format!("%{byte:02X}"));
		}
	}
	url
}

fn read_csp_sources(metadata: &BuildMetadata) -> CspSources {
	let own_origin = || vec!["'self'".to_owned()];
	let mut sources = CspSources {
		script_src: own_origin(),
		style_src: own_origin(),
		connect_src: own_origin(),
		img_src: own_origin(),
		font_src: own_origin(),
		worker_src: Vec::new(),
	};
	if !metadata.critical_css.is_empty() {
		sources.style_src.push(to_csp_hash(&metadata.critical_css));
	}
	for html in [
		&metadata.dev_head_html,
		&metadata.dev_body_prepend_html,
		&metadata.dev_body_html,
	]
	.into_iter()
	.flatten()
	{
		let inline = read_inline_contents(html);
		sources.script_src.extend(inline.scripts);
		sources.style_src.extend(inline.styles);
	}
	if let Some(dev_csp) = &metadata.dev_csp {
		let origin = &dev_csp.module_server_origin;
		for list in [
			&mut sources.script_src,
			&mut sources.style_src,
			&mut sources.img_src,
			&mut sources.font_src,
		] {
			list.push(origin.clone());
		}
		sources.connect_src.push(dev_csp.web_socket_origin.clone());
		sources.worker_src.push("blob:".to_owned());
		if let Some(nonce) = &dev_csp.nonce {
			let source = format!("'nonce-{nonce}'");
			sources.script_src.push(source.clone());
			sources.style_src.push(source);
		}
	}
	sources
}

/// The quoted hashes of inline contents.
#[derive(Default)]
struct InlineHashes {
	scripts: Vec<String>,
	styles: Vec<String>,
}

/// The hashes of the inline script and style contents of the development
/// HTML that Vite and Vorma generate. A script with a `src` attribute has no
/// inline content.
fn read_inline_contents(html: &str) -> InlineHashes {
	let mut hashes = InlineHashes::default();
	let lower = LowercaseHtml(html.to_ascii_lowercase());
	let mut position = 0;
	while let Some(offset) = lower.0[position..].find('<') {
		let start = position + offset;
		position = start + 1;
		let Some(el) = read_inline_el(html, &lower, start) else {
			continue;
		};
		match el.tag {
			"script" if !has_src_attr(&lower.0[el.attrs.clone()]) => {
				hashes.scripts.push(to_csp_hash(&html[el.content]));
			}
			"script" => {}
			_ => hashes.styles.push(to_csp_hash(&html[el.content])),
		}
		position = el.end;
	}
	hashes
}

struct InlineEl {
	tag: &'static str,
	attrs: std::ops::Range<usize>,
	content: std::ops::Range<usize>,
	end: usize,
}

/// HTML text in ASCII lowercase, in which tag names match case-insensitively.
struct LowercaseHtml(String);

/// Reads `<script …>…</script>` or `<style …>…</style>` at `start`, with a
/// case-insensitive tag name that a word character does not continue, and
/// the first matching closing tag.
fn read_inline_el(html: &str, lower: &LowercaseHtml, start: usize) -> Option<InlineEl> {
	let after_open = start + 1;
	let tag = ["script", "style"]
		.into_iter()
		.find(|tag| lower.0[after_open..].starts_with(tag))?;
	let after_tag = after_open + tag.len();
	if lower.0[after_tag..]
		.chars()
		.next()
		.is_some_and(|character| character.is_ascii_alphanumeric() || character == '_')
	{
		return None;
	}
	let open_end = after_tag + html[after_tag..].find('>')?;
	let closing = format!("</{tag}>");
	let content_start = open_end + 1;
	let content_end = content_start + lower.0[content_start..].find(&closing)?;
	Some(InlineEl {
		tag,
		attrs: after_tag..open_end,
		content: content_start..content_end,
		end: content_end + closing.len(),
	})
}

/// Whether lowercase attribute text contains `src` as a whole word followed
/// by optional whitespace and `=`.
fn has_src_attr(attrs: &str) -> bool {
	attrs.match_indices("src").any(|(index, _)| {
		let starts_word = attrs[..index]
			.chars()
			.next_back()
			.is_none_or(|character| !(character.is_ascii_alphanumeric() || character == '_'));
		starts_word && attrs[index + 3..].trim_start().starts_with('=')
	})
}

/// The build output is missing or unreadable.
#[derive(Debug)]
pub(crate) struct BuildOutputError {
	pub(crate) message: String,
	pub(crate) source: Option<Box<dyn std::error::Error + Send + Sync>>,
}

impl fmt::Display for BuildOutputError {
	fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
		formatter.write_str(&self.message)
	}
}

impl std::error::Error for BuildOutputError {
	fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
		self.source
			.as_deref()
			.map(|source| source as &(dyn std::error::Error + 'static))
	}
}

/// The build directory and its current build.
pub(crate) struct BuildOutput {
	metadata_path: PathBuf,
	public_dir: PathBuf,
	current: CurrentBuild,
}

enum CurrentBuild {
	Prod(Arc<BuildSnapshot>),
	Dev(Mutex<DevBuild>),
}

/// What a development process remembers about the metadata file.
struct DevBuild {
	/// The metadata text and the snapshot made from it.
	current: (String, Arc<BuildSnapshot>),
	/// The latest metadata text that is not valid metadata, with its error,
	/// so that the same text is neither parsed nor reported again.
	failed: Option<(String, Arc<BuildOutputError>)>,
}

impl BuildOutput {
	/// Reads the build output that the build directory holds.
	pub(crate) async fn load(build_dir: &Path) -> Result<Self, BuildOutputError> {
		let metadata_path = build_dir.join("metadata.json");
		let text = tokio::fs::read_to_string(&metadata_path)
			.await
			.map_err(|error| BuildOutputError {
				message: format!(
					"Vorma found no metadata.json in the build directory {}. Run vorma build or vorma dev before starting the application.",
					build_dir.display()
				),
				source: Some(Box::new(error)),
			})?;
		let metadata = parse_metadata(&metadata_path, &text)?;
		let snapshot = Arc::new(BuildSnapshot::new(metadata));
		let current = match snapshot.metadata.runtime_mode {
			RuntimeMode::Prod => CurrentBuild::Prod(snapshot),
			RuntimeMode::Dev => CurrentBuild::Dev(Mutex::new(DevBuild {
				current: (text, snapshot),
				failed: None,
			})),
		};
		Ok(Self {
			metadata_path,
			public_dir: build_dir.join("public"),
			current,
		})
	}

	/// A production build that exists only in memory. It has no build
	/// directory, so it has no file of a static public asset.
	pub(crate) fn from_snapshot(snapshot: Arc<BuildSnapshot>) -> Self {
		Self {
			metadata_path: PathBuf::new(),
			public_dir: PathBuf::new(),
			current: CurrentBuild::Prod(snapshot),
		}
	}

	/// The directory that holds the published static public assets.
	pub(crate) fn public_dir(&self) -> &Path {
		&self.public_dir
	}

	/// The current build. In development, this rereads the metadata file and
	/// makes a new snapshot when its text changed.
	///
	/// A failure is reported to the log. Metadata text that is not valid is
	/// reported once, and later reads of the same text return the same error
	/// without parsing it again. A file that cannot be read is reported at
	/// every read.
	pub(crate) async fn read_snapshot(&self) -> Result<Arc<BuildSnapshot>, Arc<BuildOutputError>> {
		let state = match &self.current {
			CurrentBuild::Prod(snapshot) => return Ok(Arc::clone(snapshot)),
			CurrentBuild::Dev(state) => state,
		};
		let mut state = state.lock().await;
		let text = match tokio::fs::read_to_string(&self.metadata_path).await {
			Ok(text) => text,
			Err(error) => {
				return Err(report_build_output_error(BuildOutputError {
					message: format!("Vorma could not read {}", self.metadata_path.display()),
					source: Some(Box::new(error)),
				}));
			}
		};
		if text == state.current.0 {
			state.failed = None;
			return Ok(Arc::clone(&state.current.1));
		}
		if let Some((failed_text, error)) = &state.failed
			&& *failed_text == text
		{
			return Err(Arc::clone(error));
		}
		match parse_metadata(&self.metadata_path, &text) {
			Ok(metadata) => {
				let snapshot = Arc::new(BuildSnapshot::new(metadata));
				state.current = (text, Arc::clone(&snapshot));
				state.failed = None;
				Ok(snapshot)
			}
			Err(error) => {
				let error = report_build_output_error(error);
				state.failed = Some((text, Arc::clone(&error)));
				Err(error)
			}
		}
	}
}

fn report_build_output_error(error: BuildOutputError) -> Arc<BuildOutputError> {
	tracing::error!(
		error = &error as &(dyn std::error::Error + 'static),
		"Vorma could not read the build"
	);
	Arc::new(error)
}

/// The only field that every format of the metadata file shares.
#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct MetadataFormat {
	format_version: Option<u32>,
}

fn parse_metadata(path: &Path, text: &str) -> Result<BuildMetadata, BuildOutputError> {
	let not_metadata = |error: serde_json::Error| BuildOutputError {
		message: format!("{} is not Vorma build metadata", path.display()),
		source: Some(Box::new(error)),
	};
	let format: MetadataFormat = serde_json::from_str(text).map_err(not_metadata)?;
	if format.format_version != Some(BUILD_METADATA_FORMAT_VERSION) {
		let found = format
			.format_version
			.map_or_else(|| "none".to_owned(), |version| version.to_string());
		return Err(BuildOutputError {
			message: format!(
				"{} has build metadata format version {found}, but this version of the vorma crate reads format version {BUILD_METADATA_FORMAT_VERSION}. Rebuild with matching versions of the vorma package and the vorma crate.",
				path.display()
			),
			source: None,
		});
	}
	serde_json::from_str(text).map_err(not_metadata)
}