vorma 0.86.0-pre.4

//! Form input for API endpoints: request bodies decoded into serde types.
//! Uploaded files are streamed to temporary files instead of memory.

use std::cell::RefCell;
use std::collections::BTreeMap;
use std::error::Error as StdError;
use std::fmt;
use std::io;

use bytes::{Bytes, BytesMut};
use futures_util::StreamExt;
use futures_util::stream::BoxStream;
use primitives_rs::tsgen::{self, TsGen, TypeDef, TypePhase, TypeRef, TypeRegistry};
use serde::de::value::{MapDeserializer, SeqDeserializer, StringDeserializer};
use serde::de::{self, DeserializeOwned, Deserializer, IntoDeserializer, Visitor};
use serde::{Deserialize, forward_to_deserialize_any};
use tempfile::NamedTempFile;
use tokio::io::AsyncWriteExt;

use crate::media_type::FormMediaType;

/// A request body as a stream of chunks.
#[doc(hidden)]
pub type FormBody = BoxStream<'static, Result<Bytes, Box<dyn StdError + Send + Sync>>>;

/// Endpoint input read from the request body as a form and deserialized into `Fields`.
///
/// The request's `Content-Type` must be `multipart/form-data` or
/// `application/x-www-form-urlencoded`; any other, or none, gets a 415
/// failure, and the handler does not run. A
/// multipart part with a filename is an [`UploadedFile`]; every other part is
/// text. Parts map onto `Fields` by name:
///
/// - A field takes the single part of its name. Several parts are an error.
/// - An `Option<_>` field admits an absent part. A present part is `Some`,
///   even when its text is empty.
/// - A `Vec<_>` field takes every part of its name in request order. An absent
///   repeated part needs `#[serde(default)]`.
/// - Text targeted at an integer, float, `bool`, or `char` parses with that
///   type's `FromStr`, so a `bool` accepts exactly `true` or `false`. Text also
///   names a unit enum variant, and a newtype struct reads its inner type.
/// - An [`UploadedFile`] field requires a file part, and any other field
///   requires text.
/// - Unknown parts are ignored unless `Fields` denies unknown fields.
///
/// `Fields` derives [`TsGen`], and a client call to the endpoint takes
/// `formInput`, which is a `FormData` or an object with the TypeScript shape of
/// the Rust `Fields`: [`UploadedFile`] is a `Blob`, an `Option<_>` field is
/// optional, and a `Vec<_>` field is an array. `Fields` must be a struct with named
/// fields, and each field must be a scalar, a unit enum, a newtype of one, an
/// [`UploadedFile`], an `Option<_>` of one of these or of a `Vec<_>`, or a
/// `Vec<_>` of one of these or of an `Option<_>`. A field of another shape,
/// such as a nested struct, a map, a tuple, or a flattened struct, is an error
/// in the declaration contract, which fails the build.
///
/// Input that does not fit `Fields` fails the request with status 400. A body that
/// cannot be read fails it with status 413 when a body limit stopped it and
/// with status 400 otherwise.
#[derive(Clone, Debug)]
pub struct FormInput<Fields>(pub Fields);

impl<Fields: TsGen> TsGen for FormInput<Fields> {
	fn type_ref() -> TypeRef {
		Fields::type_ref()
	}

	fn collect_type_defs(registry: &mut TypeRegistry) -> tsgen::Result<()> {
		collect_form_type_defs::<Fields>(TypePhase::Deserialize, registry)
	}

	fn type_ref_for(phase: TypePhase) -> TypeRef {
		Fields::type_ref_for(phase)
	}

	fn collect_type_defs_for(phase: TypePhase, registry: &mut TypeRegistry) -> tsgen::Result<()> {
		collect_form_type_defs::<Fields>(phase, registry)
	}
}

/// Collects `Fields`'s definitions into `registry` after checking that the form
/// decoder can read every field of `Fields`.
fn collect_form_type_defs<Fields: TsGen>(
	phase: TypePhase,
	registry: &mut TypeRegistry,
) -> tsgen::Result<()> {
	let mut collected = TypeRegistry::default();
	Fields::collect_type_defs_for(phase, &mut collected)?;
	let defs = collected.into_defs();
	check_form_fields(&Fields::type_ref_for(phase), &defs).map_err(tsgen::Error::new)?;
	for def in defs {
		registry.try_define(def)?;
	}
	Ok(())
}

/// The definition that `type_ref` stands for, following named references
/// (a newtype of a named type refers to another definition).
fn resolve_form_type<'a>(mut type_ref: &'a TypeRef, defs: &'a [TypeDef]) -> &'a TypeRef {
	for _ in 0..=defs.len() {
		let TypeRef::Named { key, .. } = type_ref else {
			break;
		};
		match defs.iter().find(|def| def.key() == key) {
			Some(def) => type_ref = def.type_ref(),
			None => break,
		}
	}
	type_ref
}

/// Checks that the form decoder can read an input type of this shape: a
/// struct whose fields it can read.
fn check_form_fields(type_ref: &TypeRef, defs: &[TypeDef]) -> Result<(), String> {
	let TypeRef::Object(fields) = resolve_form_type(type_ref, defs) else {
		return Err(
			"form input must be a struct with named fields, without flattened fields".to_owned(),
		);
	};
	for field in fields {
		check_form_field(field.type_ref(), true, defs).map_err(|problem| {
			format!(
				"the form field `{}` is {problem}, which form input cannot read",
				field.name()
			)
		})?;
	}
	Ok(())
}

/// Checks one field's type. A field takes several parts only when it is a
/// sequence at its top (`repeated`), so a sequence inside a sequence is not
/// readable.
fn check_form_field(type_ref: &TypeRef, repeated: bool, defs: &[TypeDef]) -> Result<(), String> {
	let described = match resolve_form_type(type_ref, defs) {
		TypeRef::Bool
		| TypeRef::String
		| TypeRef::Number
		| TypeRef::Integer
		| TypeRef::WideInteger { .. }
		| TypeRef::Blob
		| TypeRef::StringLiteral(_) => return Ok(()),
		TypeRef::Nullable(inner) => return check_form_field(inner, repeated, defs),
		TypeRef::Array(inner) if repeated => return check_form_field(inner, false, defs),
		TypeRef::Union(members)
			if !members.is_empty()
				&& members
					.iter()
					.all(|member| matches!(member, TypeRef::StringLiteral(_))) =>
		{
			return Ok(());
		}
		TypeRef::Array(_) => "a sequence inside a sequence",
		TypeRef::Object(_) => "a nested struct",
		TypeRef::Map(..) => "a map",
		TypeRef::Tuple(_) => "a tuple",
		TypeRef::Intersection(_) => "a flattened struct",
		TypeRef::Union(_) => "an enum with data",
		TypeRef::Unit | TypeRef::Null => "an empty value",
		TypeRef::Unknown | TypeRef::Raw(_) => "a value of unknown shape",
		TypeRef::FormData => "a form",
		TypeRef::Named { .. } => "a type that the declarations do not define",
	};
	Err(described.to_owned())
}

/// A file uploaded as one multipart part, stored in a temporary file in the
/// operating system's temporary directory, which `TMPDIR` can move.
///
/// Dropping the value deletes the file. Moving it into other work keeps the
/// file for that work, and `temp_file.persist(path)` keeps it permanently by
/// renaming it. It deserializes only from [`FormInput`]. A file input left
/// empty submits a part with an empty filename and no bytes.
#[derive(Debug)]
pub struct UploadedFile {
	/// The part's filename as submitted.
	pub file_name: String,
	/// The part's content type, when it has a well-formed one.
	pub content_type: Option<String>,
	/// The temporary file that holds the part's contents.
	pub temp_file: NamedTempFile,
}

impl TsGen for UploadedFile {
	fn type_ref() -> TypeRef {
		TypeRef::Blob
	}
}

/// Why a form's parts do not deserialize as the input type.
///
/// Messages never contain submitted values.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum FormDeserializeError {
	/// A multipart body or its boundary is malformed, or a part has no name.
	MalformedMultipartBody,
	/// The input type requires a field that the form does not contain.
	MissingField {
		/// The field's name in the input type.
		field: &'static str,
	},
	/// A single-valued field received several parts.
	MultipleValues,
	/// A text field received a file.
	UnexpectedFile,
	/// An [`UploadedFile`] field received text.
	UnexpectedText,
	/// Text does not parse as its field's type, or the input type rejected the form.
	InvalidValue,
}

impl fmt::Display for FormDeserializeError {
	fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
		match self {
			Self::MalformedMultipartBody => formatter.write_str("malformed multipart form body"),
			Self::MissingField { field } => {
				write!(formatter, "form input is missing field `{field}`")
			}
			Self::MultipleValues => {
				formatter.write_str("a single-valued form field received several parts")
			}
			Self::UnexpectedFile => formatter.write_str("a text form field received a file"),
			Self::UnexpectedText => formatter.write_str("a file form field received text"),
			Self::InvalidValue => formatter.write_str("form input does not match its input type"),
		}
	}
}

impl std::error::Error for FormDeserializeError {}

impl de::Error for FormDeserializeError {
	/// Serde messages can quote submitted values, so they are discarded.
	fn custom<M: fmt::Display>(_message: M) -> Self {
		Self::InvalidValue
	}

	fn missing_field(field: &'static str) -> Self {
		Self::MissingField { field }
	}
}

/// Why a form body could not be decoded: it does not fit the input type, it
/// could not be read, or an uploaded file could not be stored.
pub(crate) enum FormDecodeError {
	/// The body does not fit the input type.
	Invalid,
	/// The body could not be read.
	BodyRead(Box<dyn StdError + Send + Sync>),
	/// An uploaded file could not be stored.
	Storage(io::Error),
}

impl From<FormDeserializeError> for FormDecodeError {
	fn from(_error: FormDeserializeError) -> Self {
		Self::Invalid
	}
}

/// Decodes a request body as form input.
pub(crate) async fn decode_form_input<Fields: DeserializeOwned>(
	media_type: FormMediaType,
	body: FormBody,
) -> Result<Fields, FormDecodeError> {
	let fields = match media_type {
		FormMediaType::Multipart { boundary } => read_multipart_fields(boundary, body).await?,
		FormMediaType::UrlEncoded => read_urlencoded_fields(&collect_body(body).await?),
	};
	Ok(Fields::deserialize(MapDeserializer::new(
		fields
			.into_iter()
			.map(|(name, parts)| (name, FieldParts(parts))),
	))?)
}

async fn collect_body(mut body: FormBody) -> Result<Bytes, FormDecodeError> {
	let mut collected = BytesMut::new();
	while let Some(chunk) = body.next().await {
		collected.extend_from_slice(&chunk.map_err(FormDecodeError::BodyRead)?);
	}
	Ok(collected.freeze())
}

/// Submitted parts grouped by field name, each group in request order. The
/// ordered map keeps grouping linearithmic and error reporting deterministic.
type Fields = BTreeMap<String, Vec<Part>>;

/// One submitted part: a multipart part with a filename is a file.
enum Part {
	Text(String),
	File(UploadedFile),
}

fn read_urlencoded_fields(body: &[u8]) -> Fields {
	let mut fields = Fields::new();
	for (name, value) in form_urlencoded::parse(body) {
		fields
			.entry(name.into_owned())
			.or_default()
			.push(Part::Text(value.into_owned()));
	}
	fields
}

fn from_multer(error: multer::Error) -> FormDecodeError {
	match error {
		multer::Error::StreamReadFailed(error) => FormDecodeError::BodyRead(error),
		_ => FormDecodeError::Invalid,
	}
}

async fn read_multipart_fields(
	boundary: String,
	body: FormBody,
) -> Result<Fields, FormDecodeError> {
	let mut multipart = multer::Multipart::new(body, boundary);
	let mut fields = Fields::new();
	while let Some(mut field) = multipart.next_field().await.map_err(from_multer)? {
		let name = field
			.name()
			.ok_or(FormDeserializeError::MalformedMultipartBody)?
			.to_owned();
		let part = match field.file_name() {
			Some(file_name) => {
				let file_name = file_name.to_owned();
				let content_type = field.content_type().map(ToString::to_string);
				let temp_file = store_file_part(&mut field).await?;
				Part::File(UploadedFile {
					file_name,
					content_type,
					temp_file,
				})
			}
			None => Part::Text(field.text().await.map_err(from_multer)?),
		};
		fields.entry(name).or_default().push(part);
	}
	Ok(fields)
}

/// Writes one file part to a new temporary file as its chunks arrive.
async fn store_file_part(field: &mut multer::Field<'_>) -> Result<NamedTempFile, FormDecodeError> {
	let (temp_file, handle) = tokio::task::spawn_blocking(|| {
		let temp_file = NamedTempFile::new()?;
		let handle = temp_file.reopen()?;
		Ok::<_, io::Error>((temp_file, handle))
	})
	.await
	.map_err(io::Error::other)
	.and_then(|created| created)
	.map_err(FormDecodeError::Storage)?;
	let mut handle = tokio::fs::File::from_std(handle);
	while let Some(chunk) = field.chunk().await.map_err(from_multer)? {
		handle
			.write_all(&chunk)
			.await
			.map_err(FormDecodeError::Storage)?;
	}
	handle.flush().await.map_err(FormDecodeError::Storage)?;
	Ok(temp_file)
}

thread_local! {
	/// The uploaded file that [`FieldParts`] hands to [`UploadedFile`]'s
	/// visitor. Serde's data model has no value for an open file, so the
	/// deserializer stores the file here and the visitor takes it in the same
	/// synchronous call.
	static PENDING_UPLOADED_FILE: RefCell<Option<UploadedFile>> = const { RefCell::new(None) };
}

/// The newtype-struct name through which [`UploadedFile`] asks for a file part.
const UPLOADED_FILE_TOKEN: &str = "$vorma::UploadedFile";

/// Every part submitted under one field name.
struct FieldParts(Vec<Part>);

impl FieldParts {
	fn into_single(self) -> Result<Part, FormDeserializeError> {
		let [part] =
			<[Part; 1]>::try_from(self.0).map_err(|_| FormDeserializeError::MultipleValues)?;
		Ok(part)
	}

	fn into_text(self) -> Result<String, FormDeserializeError> {
		match self.into_single()? {
			Part::Text(text) => Ok(text),
			Part::File(_) => Err(FormDeserializeError::UnexpectedFile),
		}
	}
}

impl IntoDeserializer<'_, FormDeserializeError> for FieldParts {
	type Deserializer = Self;

	fn into_deserializer(self) -> Self {
		self
	}
}

macro_rules! deserialize_parsed_text {
	($($method:ident => $visit:ident,)*) => {$(
		fn $method<V: Visitor<'de>>(self, visitor: V) -> Result<V::Value, FormDeserializeError> {
			let text = self.into_text()?;
			visitor.$visit(text.parse().map_err(|_| FormDeserializeError::InvalidValue)?)
		}
	)*};
}

impl<'de> Deserializer<'de> for FieldParts {
	type Error = FormDeserializeError;

	fn deserialize_any<V: Visitor<'de>>(
		self,
		visitor: V,
	) -> Result<V::Value, FormDeserializeError> {
		visitor.visit_string(self.into_text()?)
	}

	deserialize_parsed_text! {
		deserialize_bool => visit_bool,
		deserialize_i8 => visit_i8,
		deserialize_i16 => visit_i16,
		deserialize_i32 => visit_i32,
		deserialize_i64 => visit_i64,
		deserialize_i128 => visit_i128,
		deserialize_u8 => visit_u8,
		deserialize_u16 => visit_u16,
		deserialize_u32 => visit_u32,
		deserialize_u64 => visit_u64,
		deserialize_u128 => visit_u128,
		deserialize_f32 => visit_f32,
		deserialize_f64 => visit_f64,
		deserialize_char => visit_char,
	}

	fn deserialize_option<V: Visitor<'de>>(
		self,
		visitor: V,
	) -> Result<V::Value, FormDeserializeError> {
		visitor.visit_some(self)
	}

	fn deserialize_seq<V: Visitor<'de>>(
		self,
		visitor: V,
	) -> Result<V::Value, FormDeserializeError> {
		let els = self.0.into_iter().map(|part| Self(vec![part]));
		visitor.visit_seq(SeqDeserializer::new(els))
	}

	fn deserialize_newtype_struct<V: Visitor<'de>>(
		self,
		name: &'static str,
		visitor: V,
	) -> Result<V::Value, FormDeserializeError> {
		if name != UPLOADED_FILE_TOKEN {
			return visitor.visit_newtype_struct(self);
		}
		let Part::File(file) = self.into_single()? else {
			return Err(FormDeserializeError::UnexpectedText);
		};
		PENDING_UPLOADED_FILE.with(|pending| *pending.borrow_mut() = Some(file));
		visitor.visit_unit()
	}

	fn deserialize_enum<V: Visitor<'de>>(
		self,
		_name: &'static str,
		_variants: &'static [&'static str],
		visitor: V,
	) -> Result<V::Value, FormDeserializeError> {
		visitor.visit_enum(StringDeserializer::new(self.into_text()?))
	}

	fn deserialize_ignored_any<V: Visitor<'de>>(
		self,
		visitor: V,
	) -> Result<V::Value, FormDeserializeError> {
		visitor.visit_unit()
	}

	forward_to_deserialize_any! {
		str string bytes byte_buf unit unit_struct tuple tuple_struct map struct identifier
	}
}

impl<'de> Deserialize<'de> for UploadedFile {
	fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
		deserializer.deserialize_newtype_struct(UPLOADED_FILE_TOKEN, UploadedFileVisitor)
	}
}

struct UploadedFileVisitor;

impl<'de> Visitor<'de> for UploadedFileVisitor {
	type Value = UploadedFile;

	fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
		formatter.write_str("a file part of form input")
	}

	fn visit_unit<E: de::Error>(self) -> Result<UploadedFile, E> {
		PENDING_UPLOADED_FILE
			.with(|pending| pending.borrow_mut().take())
			.ok_or_else(|| E::custom("an uploaded file deserializes only from form input"))
	}
}