rasant 1.0.0

//! Formatting module for I/O log sinks.
mod cbor;
mod color_compact;
mod color_full;
mod compact;
mod full;
mod json;

use std::io;

use crate::TimeFormat;
use crate::constant::{ATTRIBUTE_KEY_TIME, ATTRIBUTE_KEY_TIMESTAMP};
use crate::sink::LogUpdate;

/// Supported log output format for all [`sink`][crate::sink]s.
#[derive(Clone, Debug)]
pub enum OutputFormat {
	/// A compact string.
	///
	/// `2026-01-02 15:16:17.890 [INF] some log message key_1=value_1 key2=value_2`
	Compact,
	/// A compact colored string, for terminals supporting standard [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code).
	///
	/// `2026-01-02 15:16:17.890 INF some log message key_1=value_1 key2=value_2`
	ColorCompact,
	/// Full multi-line hierarchical log output.
	/// ```text
	/// 2026-01-02 15:16:17.890 [INFO   ] fixed_key_1=value_1
	///                                   ephemeral_key_2=[value_2, value_3]
	///                                   some log message
	/// ```
	Full,
	/// Colored full multi-line hierarchical log output, for terminals supporting standard [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code).
	/// ```text
	/// 2026-01-02 15:16:17.890 WARNING fixed_key_1=value_1
	///                                 ephemeral_key_2=[value_2, value_3]
	///                                 some log message
	/// ```
	ColorFull,
	/// A JSON-formatted string entry.
	///
	/// `{"timestamp":123456,"level":"info","message":"some log message","key_1":"=value_1","key_2":"=value_2"}`
	Json,
	/// [CBOR](https://cbor.io/) (a.k.a RFC 8949) binary formatting.
	Cbor,
}

/// Formatting errors.
#[derive(Clone, Debug)]
pub enum FormatterError {
	DelimiterNotAString,
}

impl OutputFormat {
	/// Returns a name for an `OutputFormat`.
	pub fn name(&self) -> String {
		match self {
			Self::Compact => "compact",
			Self::ColorCompact => "compact (w/console color)",
			Self::Full => "full",
			Self::ColorFull => "full (w/console color)",
			Self::Json => "JSON",
			Self::Cbor => "CBOR",
		}
		.into()
	}
}

/// Configuration struct for output formatting.
#[derive(Clone, Debug)]
pub struct FormatterConfig {
	/// Output formatting configuration.
	pub format: OutputFormat,
	/// Time format for log entries, as [`TimeFormat`].
	pub time_format: TimeFormat,
	/// A separator for log entries, as a slice of [`u8`]s.
	pub delimiter: Vec<u8>,
}

impl FormatterConfig {
	/// Returns the default [`FormatterConfig`], which is [`OutputFormat::Compact`] with date/time + milliseconds in local timezone.
	pub fn default() -> Self {
		compact::default_format_config()
	}

	/// Returns a default [`FormatterConfig`] for [`OutputFormat::Compact`], with date/time + milliseconds in local timezone.
	pub fn default_compact() -> Self {
		compact::default_format_config()
	}

	/// Returns a default [`FormatterConfig`] for color [`OutputFormat::ColorCompact`], with date/time + milliseconds in local timezone.
	pub fn default_color_compact() -> Self {
		color_compact::default_format_config()
	}

	/// Returns a default [`FormatterConfig`] for color [`OutputFormat::Full`], with date/time + milliseconds in local timezone.
	pub fn default_full() -> Self {
		full::default_format_config()
	}

	/// Returns a default [`FormatterConfig`] for color [`OutputFormat::ColorFull`], with date/time + milliseconds in local timezone.
	pub fn default_color_full() -> Self {
		color_full::default_format_config()
	}

	/// Returns a default [`FormatterConfig`] for [`OutputFormat::Json`], with times as milliseconds since UNIX epoch.
	pub fn default_json() -> Self {
		json::default_format_config()
	}

	/// Returns a default [`FormatterConfig`] for [`OutputFormat::Cbor`], with times as milliseconds since UNIX epoch.
	pub fn default_cbor() -> Self {
		cbor::default_format_config()
	}
}

/// Serializes and writes log updates + attributes.
#[derive(Clone, Debug)]
pub struct Formatter {
	format: OutputFormat,
	time_key: String,
	time_format: TimeFormat,
	delimiter: Vec<u8>,

	// a reusable buffer for formatting operations requiring intermediate storage
	work_buffer: Vec<u8>,
}

impl Formatter {
	/// Initializes a [`Formatter`] from a given [`FormatterConfig`]
	pub fn new(conf: FormatterConfig) -> Self {
		Self {
			format: conf.format,
			time_key: match &conf.time_format.is_integer() {
				true => String::from(ATTRIBUTE_KEY_TIMESTAMP),
				false => String::from(ATTRIBUTE_KEY_TIME),
			},
			time_format: conf.time_format,
			delimiter: conf.delimiter,
			work_buffer: Vec::new(),
		}
	}

	/// Writes a formatted [`LogUpdate`] into a [`io::Write`].
	pub fn write<T: io::Write>(&mut self, out: &mut T, update: &LogUpdate) -> io::Result<()> {
		match self.format {
			OutputFormat::Compact => compact::write(out, &self.time_format, update),
			OutputFormat::ColorCompact => color_compact::write(out, &self.time_format, update),
			OutputFormat::Full => full::write(out, &mut self.work_buffer, &self.delimiter, &self.time_format, update),
			OutputFormat::ColorFull => color_full::write(out, &mut self.work_buffer, &self.delimiter, &self.time_format, update),
			OutputFormat::Json => json::write(out, &self.time_format, &self.time_key, update),
			OutputFormat::Cbor => cbor::write(out, &mut self.work_buffer, &self.time_format, &self.time_key, update),
		}
	}

	/// Serializes a formatted [`LogUpdate`] into a [`u8`] [`Vec`]
	pub fn as_bytes(&mut self, update: &LogUpdate) -> Vec<u8> {
		let mut out: Vec<u8> = Vec::new();

		match self.write(&mut out, update) {
			Ok(_) => out,
			Err(e) => panic!("failed to convert log update {update:?} to bytes buffer: {e}"),
		}
	}

	/// Serializes a formatted [`LogUpdate`] into a [`String`].
	pub fn as_string(&mut self, update: &LogUpdate) -> String {
		let bytes = self.as_bytes(update);

		match String::from_utf8(bytes) {
			Ok(s) => s,
			Err(e) => panic!("failed to convert log update {update:?} to UTF8: {e}"),
		}
	}

	/// Returns the formatter's delimiter as a [`u8`] slice.
	pub fn delimiter(&self) -> &[u8] {
		self.delimiter.as_slice()
	}

	/// Serializes the formatter's delimiter into a [`String`].
	pub fn delimiter_as_string(&self) -> Result<String, FormatterError> {
		match String::from_utf8(self.delimiter.clone()) {
			Ok(s) => Ok(s),
			Err(_) => Err(FormatterError::DelimiterNotAString),
		}
	}

	/// Write the formatter's delimiter into a [`io::Write`].
	pub fn write_delimiter<T: io::Write>(&self, out: &mut T) -> io::Result<()> {
		match out.write(self.delimiter.as_slice()) {
			Ok(_) => Ok(()),
			Err(e) => Err(e),
		}
	}
}

/// Returns a formatted string for a [`LogUpdate`], suitable for use with ['panic!`].
pub fn as_panic_string(update: &LogUpdate) -> String {
	let mut formatter = Formatter::new(FormatterConfig {
		format: OutputFormat::Compact,
		..FormatterConfig::default_compact()
	});
	formatter.as_string(update)
}