Skip to content

feat(transactions): break the summary down by API key - #446

Merged
argszero merged 1 commit into
mainfrom
feat/transactions-by-key
Nov 12, 2026
Merged

argszero merged 1 commit into
mainfrom
feat/transactions-by-key

Conversation

@argszero

Copy link
Copy Markdown
Owner

Summary

The transactions page gives one number per metric for whatever filters are set, and nothing that says which API key spent it. The detail table carries a key name on every row, but that is per row; the only per-key aggregate in the tree is the sharing page's, which sums what an owner earns rather than what a consumer spends. This adds the missing reading: the same filters, grouped by API key.

It extends GET /api/transactions with a by_key array rather than adding a second endpoint. The grouping has to use the same filters as the detail list (time range, custom bounds, type tab, six column filters), and sharing one response means it shares the same where_sql and the same binds — so "the groups add up to summary" holds structurally instead of depending on two parameter lists staying in step. This repository has already paid for that failure once: an expire value accepted by the list endpoint and rejected by the trend one. A separate endpoint would also need a third copy of the query and time parsers, and would change TxQuery, which state_gate.rs pins.

Three conventions the aggregate inherits, each with a test:

  • It reads the tx_facts view, not transactions. Details are kept for [rollup] retain_minutes only; anything older exists solely as minute rollup rows, so reading the raw table would undercount history.
  • The group key is the view's api_key_id, not the rollup table's. The rollup table uses 0 as its NULL sentinel; the view restores it with NULLIF(…, 0). Grouping on the rollup table would fold every keyless row into a group with id = 0.
  • Entries are SUM(row_count), not COUNT(*). The latter counts view rows, i.e. minute buckets. The test fixture folds two consume rows in the same minute into one view row with row_count = 2 specifically so these two part ways.

Rows with no API key — provider-side earn / topup / expire / withdraw — form an explicit group ordered last, because silently dropping them is exactly what would break the sum. The key name comes from a scalar subquery rather than a fourth LEFT JOIN: any of the three joins in tx_joins() makes SQLite abandon the covering index and re-read the table (0.21s → 22.6s on the dev database over NFS), and src/perf_gate.rs guards that invariant. Its positive control counts the aggregate statements that go through tx_joins_if, so it moves from three to four with a comment naming the fourth.

The page renders the array under the summary cards from the same payload, so changing a filter costs no extra request.

Files

  • src/routes/wallet.rs — by_key_sql / by_key_rows, wired into the transactions handler; tests
  • src/perf_gate.rs — positive control 3 → 4 with the reason
  • src/i18n_pack.rs — re-pinned counts after six new keys
  • ui/index.html, ui/js/app.js, ui/js/i18n.js — the #tx-by-key card, renderTxByKey(), six keys in both packs
  • docs/architecture.md, ui/README.md — the endpoint line and the card's contract

Tests

  • cargo test — 614 passed, 0 failed
  • cargo clippy --all-targets -- -D warnings — clean
  • cargo fmt --check — clean
  • New tests added (routes::wallet::tests::by_key_splits_the_summary_by_api_key_and_keeps_the_keyless_group, routes::wallet::tests::by_key_survives_folding_and_deletion_of_the_details, routes::wallet::tests::counting_view_rows_would_undercount_the_per_key_entries, tx_facts::tests::counting_view_rows_is_not_counting_calls)
  • Each new test was run against the unmodified tree and fails there for the behaviour it asserts, not for a missing symbol

Related Issue

No issue — this is acceptance item ② of an internal work order (rant 2026-11-12T14:13:23), whose item ① landed as #445.

The transactions page has one number per metric once filtered: nothing says
which API key spent it. The detail table carries a key name per row, and the
only per-key aggregate in the codebase is the sharing page's, which sums what
an owner earns rather than what a consumer spends.

Add a `by_key` array to the existing `GET /api/transactions` response instead
of a second endpoint. It shares the same `where_sql` and the same binds as
`summary`, so "the groups add up to the summary" holds structurally rather
than by two parameter lists being kept in step -- the drift this repository
already paid for once when `expire` reached the list endpoint but not the
trend one.

Three conventions the grouping inherits, each with a test:

- it reads the `tx_facts` view, not `transactions`: details are kept for
  `[rollup] retain_minutes` only and older history exists solely as minute
  rollup rows;
- the group key is the view's `api_key_id`, not the rollup table's, which
  uses `0` as its NULL sentinel;
- entries are `SUM(row_count)`, not `COUNT(*)` -- the latter counts view rows,
  i.e. minute buckets.

Rows with no API key (provider-side earn / topup / expire / withdraw) form an
explicit group ordered last, because dropping them is what would break the
sum. The key name comes from a scalar subquery rather than a fourth LEFT JOIN:
any of the three joins in `tx_joins()` makes SQLite abandon the covering index
and re-read the table (0.21s -> 22.6s on the dev database).

The page renders the array under the summary cards from the same payload, so
changing a filter costs no extra request.
@argszero
argszero merged commit 411429e into main Nov 12, 2026
2 checks passed
@argszero
argszero deleted the feat/transactions-by-key branch November 12, 2026 06:54
@argszero argszero mentioned this pull request Nov 12, 2026
4 tasks done
argszero added a commit that referenced this pull request Nov 12, 2026
Two commits since v0.7.34, no schema change (still 18):

- #445 lets an API key be paused and resumed instead of only revoked.
- #446 breaks the transactions summary down by API key.

The version string moves in the five carriers deploy_gate guards: Cargo.toml,
Cargo.lock, Dockerfile (three places), docker-compose.yml (two) and the new
CHANGELOG heading.

Co-authored-by: argszero <argszero@argszerodeMac-mini.local>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant