Lines
64.3 %
Functions
32.79 %
Branches
100 %
use axum::http::HeaderMap;
use axum::http::StatusCode;
use chrono::{DateTime, Datelike, Utc};
use num_rational::Rational64;
use serde::{Deserialize, Deserializer};
use server::command::{
CmdResult, FilterEntity, FinanceEntity, ReportFilter, commodity::ListCommodities,
};
use sqlx::types::{Uuid, chrono::NaiveDate};
pub mod activity;
pub mod balance;
pub mod category_breakdown;
use server::command::report::view;
use view::AmountView;
pub struct CommodityOption {
pub id: Uuid,
pub symbol: String,
pub name: String,
}
/// A single card in the top-of-report summary strip. `is_net` flags cards
/// that show a signed net (e.g. Income − Expense) so templates can
/// style them distinctly; `highlight` is a generic accent slot.
pub struct SummaryCard {
pub label: String,
pub amounts: Vec<AmountView>,
pub is_net: bool,
pub highlight: bool,
/// Query-string fields shared by every report page to drive client-side
/// table controls. The server only needs to read `commodity_columns` (which
/// drives a template pivot) and forward `collapsed_depth` into the template
/// for initial fold state; `sort_by` is consumed purely by the frontend
/// WASM reorder logic, so the Rust handler does not parse it.
#[derive(Default, Deserialize)]
pub struct TableControlParams {
#[serde(default, deserialize_with = "empty_string_as_none")]
pub collapsed_depth: Option<String>,
pub commodity_columns: Option<String>,
impl TableControlParams {
#[must_use]
pub fn commodity_columns_enabled(&self) -> bool {
self.commodity_columns
.as_deref()
.map(str::trim)
.is_some_and(|v| v.eq_ignore_ascii_case("on") || v.eq_ignore_ascii_case("true"))
/// Chart-specific query parameters shared across report chart handlers.
/// `chart_kind` maps to `plotting::ChartKind`; `chart_series` is a
/// report-specific toggle (e.g. Activity: show Net or not) parsed in
/// each handler. `renderer` picks between server-side SVG (default)
/// and client-side canvas.
pub struct ChartParams {
pub chart_kind: Option<String>,
pub chart_series: Option<String>,
pub renderer: Option<String>,
impl ChartParams {
/// Parse `chart_kind` (`bar`, `line`, `stacked`) into a
/// `plotting::ChartKind`. Unknown / missing values fall back to
/// `Bar` so a stale URL still renders something.
pub fn chart_kind_or_default(&self) -> plotting::ChartKind {
match self.chart_kind.as_deref().map(str::to_ascii_lowercase) {
Some(ref s) if s == "line" => plotting::ChartKind::Line,
Some(ref s) if s == "stacked" || s == "stackedbar" => plotting::ChartKind::StackedBar,
_ => plotting::ChartKind::Bar,
/// Normalise the chart kind to its canonical lowercase name so
/// the template can round-trip it into URLs and `<select>`
/// values.
pub fn chart_kind_str(&self) -> String {
match self.chart_kind_or_default() {
plotting::ChartKind::Bar => "bar".to_string(),
plotting::ChartKind::StackedBar => "stacked".to_string(),
plotting::ChartKind::Line => "line".to_string(),
/// Canonicalise the renderer choice. Accepts `svg` (default) and
/// `canvas`; anything else normalises to `svg`.
pub fn renderer_str(&self) -> String {
match self.renderer.as_deref().map(str::to_ascii_lowercase) {
Some(ref s) if s == "canvas" => "canvas".to_string(),
_ => "svg".to_string(),
/// Minimal URL-query encoder for the (key, value) pairs the chart
/// endpoints take. Avoids pulling in `serde_urlencoded` just to
/// stringify a handful of params — keeps the handler simple.
pub fn encode_query(pairs: &[(&str, &str)]) -> String {
let mut out = String::new();
for (k, v) in pairs {
if v.is_empty() {
continue;
if !out.is_empty() {
out.push('&');
out.push_str(&percent_encode(k));
out.push('=');
out.push_str(&percent_encode(v));
if out.is_empty() {
out
} else {
format!("?{out}")
fn percent_encode(s: &str) -> String {
let mut out = String::with_capacity(s.len());
for b in s.bytes() {
let keep = b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_' | b'.' | b'~');
if keep {
out.push(b as char);
out.push_str(&format!("%{b:02X}"));
pub async fn load_commodities(user_id: Uuid) -> Vec<CommodityOption> {
let Ok(Some(CmdResult::TaggedEntities { entities, .. })) =
ListCommodities::new().user_id(user_id).run().await
else {
return Vec::new();
let mut commodities = Vec::new();
for (entity, tags) in entities {
if let FinanceEntity::Commodity(commodity) = entity
&& let (FinanceEntity::Tag(s), FinanceEntity::Tag(n)) = (&tags["symbol"], &tags["name"])
{
commodities.push(CommodityOption {
id: commodity.id,
symbol: s.tag_value.clone(),
name: n.tag_value.clone(),
});
commodities
/// Parse a `YYYY-MM-DD` string into UTC. `end_of_day` controls whether the
/// resulting instant sits at 00:00 (range start) or 23:59:59 (range end /
/// as-of cutoff).
pub fn parse_date_bound(raw: &str, end_of_day: bool) -> Option<DateTime<Utc>> {
let date = NaiveDate::parse_from_str(raw, "%Y-%m-%d").ok()?;
let time = if end_of_day {
date.and_hms_opt(23, 59, 59)
date.and_hms_opt(0, 0, 0)
}?;
Some(time.and_utc())
pub fn wants_json(headers: &HeaderMap) -> bool {
headers
.get("accept")
.and_then(|v| v.to_str().ok())
.is_some_and(|v| v.contains("application/json"))
/// Sum top-level rows' amounts per commodity. Used by Balance to build its
/// grand-total card(s).
pub fn sum_top_level_amounts(rows: &[view::ReportRowView]) -> Vec<AmountView> {
let mut out: Vec<AmountView> = Vec::new();
for row in rows.iter().filter(|r| r.depth == 0) {
for a in &row.amounts {
match out
.iter_mut()
.find(|x| x.commodity_symbol == a.commodity_symbol)
Some(existing) => existing.amount += a.amount,
None => out.push(AmountView {
commodity_symbol: a.commodity_symbol.clone(),
amount: a.amount,
}),
/// Collect the set of commodity symbols present across all rows, in the
/// order the row-data first mentions them. Drives the "Commodities as
/// columns" pivot: a stable column ordering without depending on the
/// user's commodity list.
pub fn commodity_symbols_in_rows(rows: &[view::ReportRowView]) -> Vec<String> {
let mut seen = Vec::new();
for row in rows {
if !seen.iter().any(|s: &String| s == &a.commodity_symbol) {
seen.push(a.commodity_symbol.clone());
seen
/// Look up a row's amount for the given commodity symbol. Called from the
/// commodity-columns branch of the tree-table template.
pub fn row_amount_by_symbol(row: &view::ReportRowView, symbol: &str) -> Option<Rational64> {
row.amounts
.iter()
.find(|a| a.commodity_symbol == symbol)
.map(|a| a.amount)
/// Parse the shared `sort_order` query param. Balance and Breakdown
/// accept the same names; this keeps the URLs consistent between
/// them. Unknown values fall back to `AmountDesc` so a stale URL
/// still renders.
pub fn parse_sort_order_shared(raw: Option<&str>) -> SharedSort {
match raw.map(str::to_ascii_lowercase).as_deref() {
Some("amount_asc") => SharedSort::AmountAsc,
Some("name_asc") => SharedSort::NameAsc,
Some("name_desc") => SharedSort::NameDesc,
_ => SharedSort::AmountDesc,
#[derive(Debug, Clone, Copy, Default)]
pub enum SharedSort {
#[default]
AmountDesc,
AmountAsc,
NameAsc,
NameDesc,
impl SharedSort {
pub fn to_str(self) -> &'static str {
match self {
Self::AmountDesc => "amount_desc",
Self::AmountAsc => "amount_asc",
Self::NameAsc => "name_asc",
Self::NameDesc => "name_desc",
/// Map to the plotting crate's balance-chart sort enum.
pub fn into_plotting_balance(self) -> plotting::adapters::SortOrder {
Self::AmountDesc => plotting::adapters::SortOrder::MagnitudeDesc,
Self::AmountAsc => plotting::adapters::SortOrder::MagnitudeAsc,
Self::NameAsc => plotting::adapters::SortOrder::NameAsc,
Self::NameDesc => plotting::adapters::SortOrder::NameDesc,
fn abs_rational(r: Rational64) -> Rational64 {
if r < Rational64::new(0, 1) { -r } else { r }
/// Sort top-level rows in place according to `order`. Children ride
/// with their parent — they're adjacent in the flattened view and we
/// preserve that adjacency by sorting on a key derived from each
/// top-level row alone.
pub fn sort_top_level_rows(rows: &mut Vec<view::ReportRowView>, order: SharedSort) {
// Group rows by their top-level ancestor. Flat projection is DFS
// order: every depth-0 row is followed by its subtree before the
// next depth-0 row, so a single pass builds the groups.
let mut groups: Vec<Vec<view::ReportRowView>> = Vec::new();
for row in std::mem::take(rows) {
if row.depth == 0 || groups.is_empty() {
groups.push(vec![row]);
} else if let Some(last) = groups.last_mut() {
last.push(row);
groups.sort_by(|a, b| {
let (a_root, b_root) = (&a[0], &b[0]);
match order {
SharedSort::AmountDesc => {
let ka = a_root.amounts.iter().map(|x| abs_rational(x.amount)).max();
let kb = b_root.amounts.iter().map(|x| abs_rational(x.amount)).max();
kb.cmp(&ka)
SharedSort::AmountAsc => {
ka.cmp(&kb)
SharedSort::NameAsc => a_root.account_name.cmp(&b_root.account_name),
SharedSort::NameDesc => b_root.account_name.cmp(&a_root.account_name),
for group in groups {
rows.extend(group);
#[cfg(test)]
mod sort_tests {
use super::*;
use view::{AmountView, ReportRowView};
fn mk_row(name: &str, depth: usize, amount: i64, parent: Option<Uuid>) -> ReportRowView {
let id = Uuid::new_v4();
ReportRowView {
account_id: id,
parent_id: parent,
account_name: name.to_string(),
depth,
has_children: false,
amounts: vec![AmountView {
commodity_symbol: "USD".to_string(),
amount: Rational64::new(amount, 1),
}],
#[test]
fn sort_keeps_children_with_parents() {
let parent_b = mk_row("Bank", 0, 500, None);
let parent_b_id = parent_b.account_id;
let parent_a = mk_row("Assets", 0, 1000, None);
let parent_c = mk_row("Cash", 0, 200, None);
let mut rows = vec![
parent_b,
mk_row("Checking", 1, 300, Some(parent_b_id)),
mk_row("Savings", 1, 200, Some(parent_b_id)),
parent_a,
parent_c,
];
sort_top_level_rows(&mut rows, SharedSort::AmountDesc);
let names: Vec<&str> = rows.iter().map(|r| r.account_name.as_str()).collect();
assert_eq!(
names,
vec!["Assets", "Bank", "Checking", "Savings", "Cash"],
"Assets first (1000), Bank + children next (500), Cash last (200)"
);
fn sort_by_name_ascending() {
mk_row("Zulu", 0, 1, None),
mk_row("Alpha", 0, 2, None),
mk_row("Mike", 0, 3, None),
sort_top_level_rows(&mut rows, SharedSort::NameAsc);
assert_eq!(names, vec!["Alpha", "Mike", "Zulu"]);
/// Breakdown equivalent of `row_amount_by_symbol`. Category Breakdown uses
/// a flat row type (`BreakdownRowView`) rather than the tree `ReportRowView`.
pub fn breakdown_row_amount_by_symbol(
row: &view::BreakdownRowView,
symbol: &str,
) -> Option<Rational64> {
pub fn empty_string_as_none<'de, D>(deserializer: D) -> Result<Option<String>, D::Error>
where
D: Deserializer<'de>,
let opt = Option::<String>::deserialize(deserializer)?;
Ok(opt.filter(|s| !s.is_empty()))
pub fn today_string() -> String {
Utc::now().date_naive().format("%Y-%m-%d").to_string()
pub fn month_start_string() -> String {
let now = Utc::now().date_naive();
NaiveDate::from_ymd_opt(now.year(), now.month(), 1)
.unwrap_or(now)
.format("%Y-%m-%d")
.to_string()
#[derive(Deserialize)]
#[serde(tag = "type")]
enum FilterItem {
#[serde(rename = "tag")]
Tag {
entities: Vec<String>,
name: String,
values: Vec<String>,
},
#[serde(rename = "account")]
Account {
account_id: String,
#[serde(default, rename = "display_name")]
_display_name: String,
include_subtree: bool,
#[serde(rename = "group")]
Group {
logic: String,
items: Vec<FilterItem>,
struct FilterGroup {
/// A refusal the caller can act on (`CmdError::Args`) is a 400; anything else
/// is ours. Logged because the status travels without a body: these handlers
/// return `StatusCode`, and htmx does not swap a 4xx, so the reason would
/// otherwise be visible to nobody.
pub(super) fn report_status(err: server::command::CmdError) -> StatusCode {
match err {
server::command::CmdError::Args(msg) => {
log::warn!("report refused: {msg}");
StatusCode::BAD_REQUEST
_ => StatusCode::INTERNAL_SERVER_ERROR,
fn build_tag_entity_filter(entity: FilterEntity, name: &str, values: &[String]) -> ReportFilter {
match values.len() {
1 => ReportFilter::Tag {
entity,
name: name.to_string(),
value: values[0].clone(),
_ => ReportFilter::TagIn {
values: values.to_vec(),
/// `Ok(None)` is an item the user has not filled in yet — a blank row, an empty
/// nested group. It contributes no condition and is skipped.
///
/// `Err` is an item that WAS filled in and is malformed. It must never be
/// silently dropped: dropping one child of an `and` widens the filter and
/// answers a narrower question with a broader report, under a 200.
fn build_filter_item(item: &FilterItem) -> Result<Option<ReportFilter>, ()> {
match item {
FilterItem::Tag {
entities,
name,
values,
} => {
if name.trim().is_empty() || values.is_empty() {
return Ok(None);
let filters = entities
.filter(|e| {
let fresh = !seen.contains(e);
if fresh {
seen.push(*e);
fresh
})
.map(|e| match e.as_str() {
"account" => Ok(build_tag_entity_filter(FilterEntity::Account, name, values)),
"transaction" => Ok(build_tag_entity_filter(
FilterEntity::Transaction,
)),
"split" => Ok(build_tag_entity_filter(FilterEntity::Split, name, values)),
_ => Err(()),
.collect::<Result<Vec<ReportFilter>, ()>>()?;
match filters.len() {
// Name and values were filled in; with no entity ticked the
// condition cannot be built, and dropping it widens the filter.
0 => Err(()),
1 => Ok(filters.into_iter().next()),
_ => Ok(Some(ReportFilter::Or(filters))),
FilterItem::Account {
account_id,
include_subtree,
..
if account_id.trim().is_empty() {
let id = account_id.parse::<Uuid>().map_err(|_| ())?;
Ok(Some(if *include_subtree {
ReportFilter::AccountSubtree(id)
ReportFilter::AccountEq(id)
}))
FilterItem::Group { logic, items } => group_filter(logic, items),
/// Every filled-in item, in order. Propagates the first malformed one.
fn build_filter_items(items: &[FilterItem]) -> Result<Vec<ReportFilter>, ()> {
let mut built = Vec::with_capacity(items.len());
for item in items {
if let Some(filter) = build_filter_item(item)? {
built.push(filter);
Ok(built)
/// Combine a group's built child filters by the group's declared logic.
/// `not` requires exactly one child. `None` refuses the report: an operator
/// the UI never emits must not quietly become `and`. Users who want
/// `Not(Or(...))` or `Not(And(...))` must nest the subgroup explicitly.
fn combine_group(logic: &str, filters: Vec<ReportFilter>) -> Option<ReportFilter> {
match logic {
"not" => match filters.len() {
1 => filters
.into_iter()
.next()
.map(|f| ReportFilter::Not(Box::new(f))),
_ => None,
"and" | "or" => match filters.len() {
0 => None,
1 => filters.into_iter().next(),
_ if logic == "or" => Some(ReportFilter::Or(filters)),
_ => Some(ReportFilter::And(filters)),
fn build_filter_from_group(group: &FilterGroup) -> Result<Option<ReportFilter>, ()> {
group_filter(&group.logic, &group.items)
/// A group's operator is validated even when the group turns out to be empty:
/// returning early on `items` left `{"logic":"xor","items":[]}` accepted.
fn group_filter(logic: &str, items: &[FilterItem]) -> Result<Option<ReportFilter>, ()> {
if !matches!(logic, "and" | "or" | "not") {
return Err(());
let filters = build_filter_items(items)?;
if filters.is_empty() {
combine_group(logic, filters).map(Some).ok_or(())
/// `Ok(None)` means no filter was asked for. A filter that was asked for and
/// could not be parsed is an error, never `None`: falling back to "no filter"
/// answers a narrower question with a broader report — right status, wrong
/// numbers, no signal to the reader.
/// # Errors
/// `StatusCode::BAD_REQUEST` when `tag_filters` is present but unparsable.
pub fn build_report_filter(
tag_filters: Option<&str>,
tag_filter_mode: Option<&str>,
) -> Result<Option<ReportFilter>, StatusCode> {
let Some(raw) = tag_filters.filter(|s| !s.is_empty()) else {
if tag_filter_mode == Some("script") {
return build_filter_from_sexpr(raw)
.map(Some)
.ok_or(StatusCode::BAD_REQUEST);
let group: FilterGroup = serde_json::from_str(raw).map_err(|_| StatusCode::BAD_REQUEST)?;
// A filter panel the user opened and left empty means "no conditions", not a
// malformed request — but its operator is still validated, so this cannot
// return early: `group_filter` answers `Ok(None)` for an empty valid group.
build_filter_from_group(&group).map_err(|()| StatusCode::BAD_REQUEST)
fn build_filter_from_sexpr(raw: &str) -> Option<ReportFilter> {
ReportFilter::from_sexpr(raw).ok()
mod tests {
/// A malformed child must not be dropped from an otherwise valid parent:
/// that widens the filter and answers a narrower question with a broader
/// report, under a 200. Reachable from the UI, which paints a bad nested
/// group red and submits it anyway.
fn a_malformed_child_does_not_silently_widen_the_filter() {
let bad_uuid = FilterItem::Account {
account_id: "not-a-uuid".to_owned(),
include_subtree: false,
_display_name: String::new(),
let group = FilterGroup {
logic: "and".to_owned(),
items: vec![tag_item("category", "food"), bad_uuid],
assert!(
build_filter_from_group(&group).is_err(),
"a bad child must fail the request, not vanish from the AND"
let nested_bad = FilterGroup {
items: vec![
tag_item("category", "food"),
FilterItem::Group {
logic: "not".to_owned(),
items: vec![tag_item("a", "1"), tag_item("b", "2")],
],
build_filter_from_group(&nested_bad).is_err(),
"a malformed NESTED group must fail too — same input, same answer at any depth"
/// A row the user has not filled in yet contributes nothing and is skipped.
fn an_unfilled_row_is_skipped_not_refused() {
items: vec![tag_item("category", "food"), tag_item("", "")],
matches!(build_filter_from_group(&group), Ok(Some(_))),
"a blank row is normal UI state"
/// An empty filter panel is well-formed JSON meaning "no conditions". It
/// must stay `Ok(None)` — rejecting it answers a legitimate request with a
/// 400 and the report panel simply stops updating.
fn an_empty_filter_group_is_no_filter_not_an_error() {
for raw in [
r#"{"logic":"and","items":[]}"#,
r#"{"logic":"or","items":[]}"#,
] {
matches!(build_report_filter(Some(raw), None), Ok(None)),
"an empty group must mean no filter: {raw}"
/// A filter that was asked for and cannot be parsed must NOT silently
/// become "no filter" — that answers a narrower question with a broader
/// report under a 200.
fn an_unparsable_filter_is_refused() {
assert!(build_report_filter(Some("{not json"), None).is_err());
assert!(build_report_filter(Some("(and"), Some("script")).is_err());
/// Absent or empty means no filter was requested at all.
fn no_filter_requested_is_ok_none() {
assert!(matches!(build_report_filter(None, None), Ok(None)));
assert!(matches!(build_report_filter(Some(""), None), Ok(None)));
fn tag_item(name: &str, value: &str) -> FilterItem {
entities: vec!["transaction".to_owned()],
name: name.to_owned(),
values: vec![value.to_owned()],
fn not_group_with_single_child_becomes_not() {
items: vec![tag_item("category", "food")],
let result = build_filter_from_group(&group)
.expect("filter built")
.expect("a condition");
match result {
ReportFilter::Not(inner) => match *inner {
ReportFilter::Tag { name, value, .. } => {
assert_eq!(name, "category");
assert_eq!(value, "food");
other => panic!("expected inner Tag, got {other:?}"),
other => panic!("expected Not(Tag), got {other:?}"),
fn not_group_with_zero_children_contributes_nothing() {
items: vec![],
matches!(build_filter_from_group(&group), Ok(None)),
"an unfilled group is no condition, not a malformed request"
fn not_group_with_multiple_children_is_refused() {
items: vec![tag_item("category", "food"), tag_item("category", "rent")],
"multi-child NOT is malformed; dropping it would widen the filter"
fn explicit_not_of_or_via_nesting() {
// Users who want Not(Or(food, rent)) nest an OR subgroup inside a NOT.
items: vec![FilterItem::Group {
logic: "or".to_owned(),
let ReportFilter::Not(inner) = result else {
panic!("expected Not");
let ReportFilter::Or(children) = *inner else {
panic!("expected Not(Or(..))");
assert_eq!(children.len(), 2);
fn and_group_unchanged() {
items: vec![tag_item("category", "food"), tag_item("project", "roof")],
assert!(matches!(result, ReportFilter::And(v) if v.len() == 2));
/// A row the user filled in but that cannot be turned into a condition is
/// malformed, not blank: dropping it widens the filter under a 200.
fn a_tag_row_with_no_entity_ticked_is_refused() {
let item = FilterItem::Tag {
entities: vec![],
name: "category".to_owned(),
values: vec!["food".to_owned()],
assert!(build_filter_item(&item).is_err());
/// The other direction: a row nobody touched is skipped, not refused.
fn a_blank_account_row_is_skipped_not_refused() {
let blank = FilterItem::Account {
account_id: " ".to_owned(),
assert!(matches!(build_filter_item(&blank), Ok(None)));
items: vec![tag_item("category", "food"), blank],
assert!(matches!(
build_filter_from_group(&group),
Ok(Some(ReportFilter::Tag { .. }))
));
/// An operator the UI never emits must not quietly become AND.
fn an_unknown_group_operator_is_refused() {
for logic in ["xor", "", "AND"] {
logic: logic.to_owned(),
items: vec![tag_item("category", "food"), tag_item("payee", "shop")],
"{logic} must not be accepted as AND"
/// The operator was validated only after the items were built, so an
/// unknown one slipped through whenever the group happened to be empty.
fn an_unknown_group_operator_is_refused_even_when_empty() {
logic: "xor".to_owned(),
assert!(build_filter_from_group(&group).is_err());
/// Duplicate entities each cloned the whole value list, turning a small
/// payload into an arbitrarily large one before any cap was consulted.
fn repeated_entities_build_one_condition_each() {
entities: vec!["account".to_owned(); 500],
build_filter_item(&item),
/// The entry point short-circuited on empty items, so an unknown operator
/// was never validated — the report ran unfiltered under a 200.
fn an_unknown_operator_is_refused_through_the_entry_point() {
build_report_filter(Some(r#"{"logic":"xor","items":[]}"#), None).err(),
Some(StatusCode::BAD_REQUEST)
// A panel opened and left empty is still no filter, not an error.
build_report_filter(Some(r#"{"logic":"and","items":[]}"#), None),
Ok(None)