hub: review fix 4 — the hub writes the household's receipt; a box cannot word it or flood it (D84)

offsite_end_scheduled bypasses the household's switches and went through the
ordinary customer leg: subject and body were the box's own sentence, and 50
invented subjects gave 50 mails.

- processReceipt: the details must name a checked app (app-name shape, not
  reserved) and two parsed dates; the mail is rendered only from the hub's
  bundle with that app and the parsed end date — never the box's message.
- The cooldown key is the checked app + the parsed time of the press.
- At most 5 receipts per household in 24 hours, counted in the hub's sent log;
  drops are said once a day; old receipt keys leave the cooldown map.
- Pinned: a blocked household and a household with no address get none.

Tests seen red before the fix; 12 mutations seen red, 3 after a redo
(documentation/audits/build-release-4-2026-11-15/A/redproof-review-4.txt).

Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS
This commit is contained in:
admin committed 2026-11-15 14:46:27 +01:00
1 parent 875c339cf5
commit be272b7cf4
10 files changed
+455 -26

No files matched your search

@@ -1892,7 +1892,10 @@ part alone, exactly as before, and still raises `offsite_snapshots_vanished`.
**The mail (D84)** `[FACT — built, not released]`. At the press the box sends `offsite_end_scheduled`; the hub mails
it to the household's own notification address — once per press, in the household's language, whatever its group
switches say (a receipt: `notify.householdReceiptEvents`), and not to the operator. **A household with no
switches say (a receipt: `notify.householdReceiptEvents`), and not to the operator. **The hub writes the mail, not the
box** (review of 2026-11-15): subject and body come from the hub's own bundle, with an app name the hub checked and
the end date it parsed from the details; the box's sentence is never mailed. A household gets at most 5 receipts in
24 hours (counted in the hub's sent log); the rest are dropped and said once a day in the hub's log. **A household with no
notification address gets no mail: the page is all it has.** A blocked household gets none either.
**Edge cases, each with its rule and its test.**
@@ -1985,7 +1988,7 @@ final dot (`2026. 12. 15.`), so the Hungarian sentences have no dot after it.
| A press that is refused (the app is installed; no hub tier) | „Ennek az alkalmazásnak a távoli másolatait most nem lehet törlésre kijelölni.” | "The off-site copies of this app cannot be marked for deletion now." |
| A record that could not be saved | „Nem sikerült elmenteni. Próbáld újra.” | "This could not be saved. Try again." |
| **The mail — subject** | „[Felhom] Információ: {app}: a távoli másolatok törlésre kijelölve” | "[Felhom] Information: {app}: the off-site copies are marked for deletion" |
| **The mail — body** (inside the hub's ordinary household mail frame: greeting, server, time, level, type, sign-off) | „{app}: az alkalmazás távoli másolatai törlésre vannak kijelölve. Törlésük napja: {dátum} Addig a Mentések oldalon a „Mégis megtartom” gombbal visszavonhatod.” | "{app}: the off-site copies of this app are marked for deletion. They are deleted on: {date}. Until then you can take this back on the Backups page with the “Keep it after all” button." |
| **The mail — body** (the HUB's own sentence, `mail.receipt.offsite_end_scheduled`, inside the hub's ordinary household mail frame: greeting, server, time, level, type, sign-off; the box's event carries the same sentence for the event list only) | „{app}: az alkalmazás távoli másolatai törlésre vannak kijelölve. Törlésük napja: {dátum} Addig a Mentések oldalon a „Mégis megtartom” gombbal visszavonhatod.” | "{app}: the off-site copies of this app are marked for deletion. They are deleted on: {date}. Until then you can take this back on the Backups page with the “Keep it after all” button." |
No mail to the household at the deletion: it can do nothing with it (`08` §8.1). The operator's records are
`offsite_ended_app_removed` (info, per app, not mailed) and `offsite_ended_app_refused` (warning) — `08` §6.5.
@@ -0,0 +1,105 @@
FINDING 4 — offsite_end_scheduled let a box mail its household without limit and with its own words.
### RED: the new tests on the hub code before the fix (felhom.eu 875c339c)
=== RUN TestD84_Receipt_ABoxCannotFloodOrWordTheHouseholdsMail
d84_receipt_bounds_test.go:31: 50 mail(s) for receipts that name no app; subject="[Felhom] Információ: ANY WORDS THE BOX CHOOSES: pay at http://evil.example"
--- FAIL: TestD84_Receipt_ABoxCannotFloodOrWordTheHouseholdsMail (0.06s)
=== RUN TestD84_Receipt_IsBuiltFromCheckedDetailsOnly
d84_receipt_bounds_test.go:81: removed_at is not a time: a mail went out: "[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve"
d84_receipt_bounds_test.go:81: ends_at is not a time: a mail went out: "[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve"
d84_receipt_bounds_test.go:81: ends before it was removed: a mail went out: "[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve"
d84_receipt_bounds_test.go:81: no details: a mail went out: "[Felhom] Információ: box words"
d84_receipt_bounds_test.go:81: a reserved name: a mail went out: "[Felhom] Információ: traefik: a távoli másolatok törlésre kijelölve"
d84_receipt_bounds_test.go:81: the shares: a mail went out: "[Felhom] Információ: _shares: a távoli másolatok törlésre kijelölve"
d84_receipt_bounds_test.go:81: no stack_name: a mail went out: "[Felhom] Információ: box words"
d84_receipt_bounds_test.go:81: details are not JSON: a mail went out: "[Felhom] Információ: box words"
d84_receipt_bounds_test.go:81: a sentence as the app name: a mail went out: "[Felhom] Információ: pay now at evil.example: a távoli másolatok törlésre kijelölve"
d84_receipt_bounds_test.go:81: markup as the app name: a mail went out: "[Felhom] Információ: <b>x</b>: a távoli másolatok törlésre kijelölve"
d84_receipt_bounds_test.go:89: the mail must carry the parsed end date and none of the box's text: [{to:customer@example.com subject:[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve body:Kedves Ügyfél!
--- FAIL: TestD84_Receipt_IsBuiltFromCheckedDetailsOnly (0.49s)
=== RUN TestD84_Receipt_ABlockedHouseholdGetsNone
--- PASS: TestD84_Receipt_ABlockedHouseholdGetsNone (0.04s)
FAIL
FAIL gitea.dooplex.hu/admin/felhom-hub/internal/notify 0.613s
FAIL
(TestD84_Receipt_ABlockedHouseholdGetsNone passed before the fix too: the customer leg already skipped a blocked household. It is a pin, and it has its own mutation below.)
### After the fix: mutations
== MUTATION: the receipt goes through the ordinary customer leg again (the box's words, the box's subject)
RED on the mutant, GREEN on the real file
--- FAIL: TestD84_Receipt_ABoxCannotFloodOrWordTheHouseholdsMail (0.04s)
d84_receipt_bounds_test.go:38: 50 presses in one burst gave 0 mails, want the daily limit 5
--- FAIL: TestD84_Receipt_IsBuiltFromCheckedDetailsOnly (0.48s)
d84_receipt_bounds_test.go:89: the mail must carry the parsed end date and none of the box's text: []
== MUTATION: no daily limit
*** NOT A RED-PROOF *** (mutant rc=1 built=False real rc=0)
FAIL gitea.dooplex.hu/admin/felhom-hub/internal/notify [build failed]
internal/notify/dispatcher.go:872:2: declared and not used: sentToday
== MUTATION: the limit trusts the sent log alone (a burst is faster than the log)
*** NOT A RED-PROOF *** (mutant rc=0 built=True real rc=0)
== MUTATION: the app name is not checked
RED on the mutant, GREEN on the real file
--- FAIL: TestD84_Receipt_IsBuiltFromCheckedDetailsOnly (0.40s)
d84_receipt_bounds_test.go:81: a sentence as the app name: a mail went out: "[Felhom] Információ: pay now at evil.example: a távoli másolatok törlésre kijelölve"
d84_receipt_bounds_test.go:81: the shares: a mail went out: "[Felhom] Információ: _shares: a távoli másolatok törlésre kijelölve"
d84_receipt_bounds_test.go:81: markup as the app name: a mail went out: "[Felhom] Információ: <b>x</b>: a távoli másolatok törlésre kijelölve"
== MUTATION: a reserved name gets a receipt
RED on the mutant, GREEN on the real file
--- FAIL: TestD84_Receipt_IsBuiltFromCheckedDetailsOnly (0.44s)
d84_receipt_bounds_test.go:81: a reserved name: a mail went out: "[Felhom] Információ: traefik: a távoli másolatok törlésre kijelölve"
== MUTATION: the dates are not checked
RED on the mutant, GREEN on the real file
--- FAIL: TestD84_Receipt_IsBuiltFromCheckedDetailsOnly (0.46s)
d84_receipt_bounds_test.go:81: removed_at is not a time: a mail went out: "[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve"
d84_receipt_bounds_test.go:81: ends_at is not a time: a mail went out: "[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve"
d84_receipt_bounds_test.go:81: ends before it was removed: a mail went out: "[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve"
== MUTATION: an end before the press is accepted
RED on the mutant, GREEN on the real file
--- FAIL: TestD84_Receipt_IsBuiltFromCheckedDetailsOnly (0.49s)
d84_receipt_bounds_test.go:81: ends before it was removed: a mail went out: "[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve"
== MUTATION: the press's key is the app alone
RED on the mutant, GREEN on the real file
--- FAIL: TestD84_Receipt_OncePerPress (0.04s)
d84_receipt_test.go:97: three presses gave 2 mails, want 3: [{to:customer@example.com subject:[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve body:Kedves Ügyfél!
== MUTATION: the press's time is keyed as the box wrote it (another zone = another press)
RED on the mutant, GREEN on the real file
--- FAIL: TestD84_Receipt_IsBuiltFromCheckedDetailsOnly (0.47s)
d84_receipt_bounds_test.go:96: one press sent twice with a changed subject gave 2 mails
== MUTATION: a blocked household gets the receipt
RED on the mutant, GREEN on the real file
--- FAIL: TestD84_Receipt_ABlockedHouseholdGetsNone (0.04s)
d84_receipt_bounds_test.go:108: a blocked household was mailed: [{to:customer@example.com subject:[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve body:Kedves Ügyfél!
== MUTATION: old presses stay in the cooldown map (and count against today)
*** NOT A RED-PROOF *** (mutant rc=1 built=False real rc=0)
FAIL gitea.dooplex.hu/admin/felhom-hub/internal/notify [build failed]
internal/notify/dispatcher.go:879:9: declared and not used: at
== MUTATION: the mail's date is today, not the parsed end
RED on the mutant, GREEN on the real file
--- FAIL: TestD84_Receipt_IsBuiltFromCheckedDetailsOnly (0.47s)
d84_receipt_bounds_test.go:89: the mail must carry the parsed end date and none of the box's text: [{to:customer@example.com subject:[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve body:Kedves Ügyfél!
--- FAIL: TestD84_Receipt_ReachesTheHouseholdWhateverItsSwitches (0.04s)
d84_receipt_test.go:54: the body lacks "2026. 12. 15.":
12 mutations, 3 not a red-proof
### the three mutations done again
== MUTATION: REDO (the first mutant did not compile): no daily limit
RED on the mutant, GREEN on the real file
--- FAIL: TestD84_Receipt_ABoxCannotFloodOrWordTheHouseholdsMail (0.07s)
d84_receipt_bounds_test.go:38: 50 presses in one burst gave 50 mails, want the daily limit 5
--- FAIL: TestD84_Receipt_TheDailyLimitSurvivesARestart (0.04s)
d84_receipt_bounds_test.go:168: after a restart the household got mail number 6 of the day (limit 5)
== MUTATION: REDO (the first mutant was built wrongly: it left the part it meant to remove; and the test that sees this one was added): the limit does not read the sent log (a restart gives five more)
RED on the mutant, GREEN on the real file
--- FAIL: TestD84_Receipt_TheDailyLimitSurvivesARestart (0.05s)
d84_receipt_bounds_test.go:168: after a restart the household got mail number 6 of the day (limit 5)
== MUTATION: REDO (the first mutant did not compile): old presses stay in the cooldown map (and count against today)
RED on the mutant, GREEN on the real file
--- FAIL: TestD84_Receipt_OldPressesLeaveTheCooldownMap (0.04s)
d84_receipt_bounds_test.go:133: 30 presses of yesterday must not count against today's limit: 0 mail(s)
3 mutations, 0 not a red-proof
NOT PROVEN, said plainly: the in-memory half of the limit (`inFlight >= receiptsPerDay`). In a test the events are
processed one after another, so the sent log is always written before the next one is judged and the log half
alone holds the limit. The memory half is for a burst processed in parallel; it stays in the code and is not claimed.
+14
View File
@@ -1,5 +1,19 @@
## Unreleased (after v0.182.0)
- **Review fix 4 (2026-11-15): a box can no longer word or flood the household's receipt.** `offsite_end_scheduled`
bypasses the household's switches, and it went through the ordinary customer leg: the subject and body were the
box's own sentence, and 50 invented subjects gave 50 mails. Now `Dispatcher.processReceipt`: the details must name
an app of the app-name shape that is not reserved and two parsed dates (the end after the press, at most 40 days);
the mail is rendered ONLY from the hub's bundle (new `mail.receipt.offsite_end_scheduled`, both languages) with
that app and the parsed end date — the box's `message` is never mailed; the cooldown key is the checked app + the
parsed time of the press, not the box's `subject`; **at most 5 receipts per household in 24 hours**, counted in the
hub's own sent log (`store.CountCustomerSentSince`, so a restart gives no more); drops are said once a day per
household; a household's receipt keys older than a day leave the cooldown map. A blocked household and a household
with no address get none (pinned). Tests `TestD84_Receipt_ABoxCannotFloodOrWordTheHouseholdsMail`,
`TestD84_Receipt_IsBuiltFromCheckedDetailsOnly` (seen red before the fix), `TestD84_Receipt_ABlockedHouseholdGetsNone`,
`TestD84_Receipt_OldPressesLeaveTheCooldownMap`, `TestD84_Receipt_TheDailyLimitSurvivesARestart`; 12 mutations seen
red, 3 after a redo; the in-memory half of the limit is not provable in a sequential test and is said so
(`…/A/redproof-review-4.txt`).
- **Review fix 1 (2026-11-15): a box that lies about its app list can no longer have the whole store agreed in one
window with no signal.** The hub's 30-day check rests on what the box reports, so a box could name an app that
never existed (or stop listing a living one), wait 30 days, and get every snapshot agreed beside the cap. Now:
+1
View File
@@ -90,6 +90,7 @@
"mail.event.app_update_held": "%s: the app is stopped and needs a restore",
"mail.event.app_stopped_unhealthy": "%s: the app was stopped because it kept crashing",
"mail.event.offsite_end_scheduled": "%s: the off-site copies are marked for deletion",
"mail.receipt.offsite_end_scheduled": "%s: the off-site copies of this app are marked for deletion. They are deleted on: %s. Until then you can take this back on the Backups page with the “Keep it after all” button.",
"mail.event.app_held": "An app is stopped and waits for a person to act",
"mail.event.app_hold_cleared": "The app is no longer held",
"mail.event.app_held_reminder": "An app is still held",
+1
View File
@@ -90,6 +90,7 @@
"mail.event.app_update_held": "%s: az alkalmazás leállítva, visszaállítás szükséges",
"mail.event.app_stopped_unhealthy": "%s: az alkalmazást leállítottuk, mert újra és újra összeomlott",
"mail.event.offsite_end_scheduled": "%s: a távoli másolatok törlésre kijelölve",
"mail.receipt.offsite_end_scheduled": "%s: az alkalmazás távoli másolatai törlésre vannak kijelölve. Törlésük napja: %s Addig a Mentések oldalon a „Mégis megtartom” gombbal visszavonhatod.",
"mail.event.app_held": "Egy alkalmazás le van állítva, és emberi beavatkozásra vár",
"mail.event.app_hold_cleared": "Az alkalmazás leállítása megszűnt",
"mail.event.app_held_reminder": "Egy alkalmazás még mindig le van állítva",
@@ -0,0 +1,170 @@
package notify
import (
"fmt"
"strings"
"testing"
"time"
)
// Review of 2026-11-15, finding 4: `offsite_end_scheduled` let a box mail its household without limit and with its
// own words — 50 subjects gave 50 mails, and the subject and body were the box's sentence. A receipt is now built by
// the HUB alone, from a checked app name and parsed dates; a household gets at most receiptsPerDay of them a day.
// RED-PROOF: documentation/audits/build-release-4-2026-11-15/A/redproof-review-4.txt.
func receiptDet(app string, removed time.Time) string {
return fmt.Sprintf(`{"stack_name":%q,"removed_at":%q,"ends_at":%q,"subject":"whatever the box says"}`,
app, removed.UTC().Format(time.RFC3339), removed.Add(30*24*time.Hour).UTC().Format(time.RFC3339))
}
// A box that posts free words under many subjects: no mail carries its words, and the household gets at most the
// daily limit — whatever the subjects, the app names or the times it invents.
func TestD84_Receipt_ABoxCannotFloodOrWordTheHouseholdsMail(t *testing.T) {
d, mails := receiptDispatcher(t, "customer@example.com", []string{})
evil := "ANY WORDS THE BOX CHOOSES: pay at http://evil.example"
now := time.Now().UTC()
// 50 subjects with no app at all (the review's reproduction): not one mail
for i := 0; i < 50; i++ {
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", evil, evil, fmt.Sprintf(`{"subject":"x%d"}`, i), "controller")
}
if len(*mails) != 0 {
t.Fatalf("%d mail(s) for receipts that name no app; subject=%q", len(*mails), (*mails)[0].subject)
}
// 50 valid-looking presses, each another app and another time, each with the box's own words
for i := 0; i < 50; i++ {
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", evil, evil, receiptDet(fmt.Sprintf("app-%d", i), now.Add(-time.Duration(i)*time.Minute)), "controller")
}
if len(*mails) != receiptsPerDay {
t.Fatalf("50 presses in one burst gave %d mails, want the daily limit %d", len(*mails), receiptsPerDay)
}
for _, m := range *mails {
if strings.Contains(m.subject, "evil") || strings.Contains(m.body, "evil") || strings.Contains(m.body, "ANY WORDS") {
t.Fatalf("the box's own words reached the household:\n%s\n%s", m.subject, m.body)
}
if !strings.Contains(m.subject, "a távoli másolatok törlésre kijelölve") || !strings.Contains(m.body, "Mégis megtartom") {
t.Fatalf("not the hub's own receipt:\n%s\n%s", m.subject, m.body)
}
}
// the cooldown map did not grow with the box's inventions
d.mu.Lock()
n := 0
for k := range d.custCooldowns {
if strings.HasPrefix(k, "c1:offsite_end_scheduled") {
n++
}
}
d.mu.Unlock()
if n > receiptsPerDay {
t.Fatalf("the cooldown map holds %d receipt keys for one household, want at most %d", n, receiptsPerDay)
}
}
// What the mail says comes from the details the hub CHECKED: the app name's shape, the dates as times.
func TestD84_Receipt_IsBuiltFromCheckedDetailsOnly(t *testing.T) {
now := time.Now().UTC()
good := func(app string) string { return receiptDet(app, now) }
for name, det := range map[string]string{
"no stack_name": `{"removed_at":"2026-11-15T10:00:00Z","ends_at":"2026-12-15T10:00:00Z"}`,
"a sentence as the app name": strings.Replace(good("x"), `"x"`, `"pay now at evil.example"`, 1),
"markup as the app name": strings.Replace(good("x"), `"x"`, `"<b>x</b>"`, 1),
"a reserved name": good("traefik"),
"the shares": good("_shares"),
"removed_at is not a time": `{"stack_name":"vikunja","removed_at":"yesterday","ends_at":"2026-12-15T10:00:00Z"}`,
"ends_at is not a time": `{"stack_name":"vikunja","removed_at":"2026-11-15T10:00:00Z","ends_at":"soon; click evil.example"}`,
"ends before it was removed": `{"stack_name":"vikunja","removed_at":"2026-11-15T10:00:00Z","ends_at":"2026-11-01T10:00:00Z"}`,
"details are not JSON": `not json`,
"no details": ``,
} {
d, mails := receiptDispatcher(t, "customer@example.com", nil)
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "box words", "box words", det, "controller")
if len(*mails) != 0 {
t.Errorf("%s: a mail went out: %q", name, (*mails)[0].subject)
}
}
// the date in the mail is the PARSED ends_at, in the household's date form — not text from the box
d, mails := receiptDispatcher(t, "customer@example.com", nil)
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "Törlésük napja: 1999. 01. 01.", "",
`{"stack_name":"vikunja","removed_at":"2026-11-15T10:00:00Z","ends_at":"2026-12-15T10:00:00Z"}`, "controller")
if len(*mails) != 1 || !strings.Contains((*mails)[0].body, "2026. 12. 15.") || strings.Contains((*mails)[0].body, "1999") {
t.Fatalf("the mail must carry the parsed end date and none of the box's text: %+v", *mails)
}
// the press's key is the checked app + the parsed time: the same press again, with another `subject` and the time
// written in another zone, is NOT a second mail
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "x", "",
`{"stack_name":"vikunja","removed_at":"2026-11-15T11:00:00+01:00","ends_at":"2026-12-15T10:00:00Z","subject":"another"}`, "controller")
if len(*mails) != 1 {
t.Fatalf("one press sent twice with a changed subject gave %d mails", len(*mails))
}
}
// A blocked household gets no receipt.
func TestD84_Receipt_ABlockedHouseholdGetsNone(t *testing.T) {
d, mails := receiptDispatcher(t, "customer@example.com", nil)
if err := d.store.SetCustomerConfigStatus("c1", "blocked"); err != nil {
t.Fatal(err)
}
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "x", "", receiptDet("vikunja", time.Now()), "controller")
if len(*mails) != 0 {
t.Fatalf("a blocked household was mailed: %+v", *mails)
}
if err := d.store.SetCustomerConfigStatus("c1", "active"); err != nil {
t.Fatal(err)
}
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "x", "", receiptDet("vikunja", time.Now()), "controller")
if len(*mails) != 1 {
t.Fatalf("positive control: an unblocked household must get the receipt, got %d", len(*mails))
}
}
// The map of mailed presses does not grow for ever: a household's receipt keys older than a day go at its next
// receipt; another household's keys and other event types' keys are not touched.
func TestD84_Receipt_OldPressesLeaveTheCooldownMap(t *testing.T) {
d, mails := receiptDispatcher(t, "customer@example.com", nil)
old := time.Now().Add(-25 * time.Hour)
d.mu.Lock()
for i := 0; i < 30; i++ {
d.custCooldowns[fmt.Sprintf("c1:offsite_end_scheduled:old-%d|x", i)] = old
}
d.custCooldowns["c2:offsite_end_scheduled:other|x"] = old
d.custCooldowns["c1:app_update_undone:vikunja"] = old
d.mu.Unlock()
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "x", "", receiptDet("vikunja", time.Now()), "controller")
if len(*mails) != 1 {
t.Fatalf("30 presses of yesterday must not count against today's limit: %d mail(s)", len(*mails))
}
d.mu.Lock()
defer d.mu.Unlock()
n := 0
for k := range d.custCooldowns {
if strings.HasPrefix(k, "c1:offsite_end_scheduled:") {
n++
}
}
if n != 1 {
t.Fatalf("the household's receipt keys: %d, want only today's one", n)
}
if _, ok := d.custCooldowns["c2:offsite_end_scheduled:other|x"]; !ok {
t.Fatal("another household's key was removed")
}
if _, ok := d.custCooldowns["c1:app_update_undone:vikunja"]; !ok {
t.Fatal("another event type's key was removed")
}
}
// The daily limit is the hub's own SENT LOG, so a hub restart (an empty map) does not give a box five more.
func TestD84_Receipt_TheDailyLimitSurvivesARestart(t *testing.T) {
d, mails := receiptDispatcher(t, "customer@example.com", nil)
for i := 0; i < receiptsPerDay; i++ {
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "x", "", receiptDet(fmt.Sprintf("app-%d", i), time.Now()), "controller")
}
if len(*mails) != receiptsPerDay {
t.Fatalf("fixture: %d mails", len(*mails))
}
d.mu.Lock()
d.custCooldowns = map[string]time.Time{} // the restart
d.mu.Unlock()
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "x", "", receiptDet("one-more", time.Now()), "controller")
if len(*mails) != receiptsPerDay {
t.Fatalf("after a restart the household got mail number %d of the day (limit %d)", len(*mails), receiptsPerDay)
}
}
+1 -1
View File
@@ -83,7 +83,7 @@ func TestD84_Receipt_FollowsTheHouseholdsLanguage(t *testing.T) {
func TestD84_Receipt_OncePerPress(t *testing.T) {
d, mails := receiptDispatcher(t, "customer@example.com", nil)
send := func(app, removedAt string) {
det := `{"stack_name":"` + app + `","removed_at":"` + removedAt + `","subject":"` + app + `|` + removedAt + `"}`
det := `{"stack_name":"` + app + `","removed_at":"` + removedAt + `","ends_at":"2026-12-15T10:00:00Z","subject":"` + app + `|` + removedAt + `"}`
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "x "+app, "", det, "controller")
}
send("vikunja", "2026-11-15T10:00:00Z")
+148 -21
View File
@@ -32,6 +32,8 @@ type Dispatcher struct {
mu sync.Mutex
opCooldowns map[string]time.Time // "customerID:eventType" → last operator notify
custCooldowns map[string]time.Time // "customerID:eventType" → last customer notify
// receiptDropDay: per household, the UTC day on which a dropped receipt was last said in the log (once a day).
receiptDropDay map[string]string
// sendEmailFn is the email sender, seam-injected so tests exercise routing without real HTTP.
// Defaults to (*Dispatcher).sendEmail (Resend) in NewDispatcher. headers (nil = none) become
@@ -248,7 +250,7 @@ func (d *Dispatcher) processEvent(customerID, eventType, severity, message, mess
// Before the severity gate (the event is `info`: nothing is wrong) and with no operator mail: the event row is
// the operator's record.
if householdReceiptEvents[eventType] {
d.processCustomer(customerID, eventType, severity, message, messageCustomer, detailsJSON, source)
d.processReceipt(customerID, eventType, severity, detailsJSON)
return
}
@@ -777,31 +779,158 @@ var recordOnlyEvents = map[string]bool{
// deleted and how to take it back. The reviewer's reason, accepted by the operator: the page alone does not warn a
// household whose login someone else uses.
//
// THREE THINGS FOLLOW FROM THAT REASON, each pinned by TestD84_Receipt*:
// - it goes to the household's own notification address by the customer leg (processCustomer) — no second path;
// - it does NOT read the household's group switches (`enabled_events`): whoever holds the login could switch a
// group off first, and this is not a detector the household tunes — it is a receipt;
// - its cooldown is per PRESS (details `subject` = app + the record's own time), so two apps removed in one hour
// are two mails, and one press delivered twice is one mail.
// A receipt bypasses the household's group switches (whoever holds the login could switch a group off first) — so it
// is the one household mail a BOX can cause whatever the household chose, and it is built so a box can do nothing
// else with it (review of 2026-11-15; processReceipt):
// - THE HUB WRITES IT. Subject and body come only from the hub's own bundle, with an app name the hub checked
// (the shape of an app name, not reserved) and dates the hub parsed. The box's `message` is never mailed.
// - ONE PER PRESS. The cooldown key is the checked app + the parsed time of the press — not the box's free
// `subject` — so one press delivered twice is one mail, and two apps removed in one hour are two.
// - AT MOST receiptsPerDay PER HOUSEHOLD IN 24 HOURS, counted in the hub's own sent log (it survives a restart).
// The rest are dropped; the hub says so once a day per household.
// - to the household's own notification address by the customer leg's own delivery; never to the operator.
//
// A household with NO address gets no mail — the page is all it has (`07` §8.2f). A blocked household gets none.
// The operator is not mailed: the event row is the record.
// Pinned by TestD84_Receipt*.
var householdReceiptEvents = map[string]bool{
"offsite_end_scheduled": true,
}
// receiptSubjectSuffix returns ":"+subject for a receipt whose details carry a non-empty `subject`.
func receiptSubjectSuffix(eventType, detailsJSON string) string {
if !householdReceiptEvents[eventType] {
return ""
}
// receiptsPerDay is the most receipts ONE household is mailed in 24 hours (review of 2026-11-15).
const receiptsPerDay = 5
// receiptCooldown: the same press is never mailed twice within this time.
const receiptCooldown = 24 * time.Hour
// receipt is what the hub accepts of a receipt's details.
type receipt struct {
App string
Removed time.Time
Ends time.Time
}
// parseReceipt checks a receipt's details. ok=false → nothing is mailed. The app must have the shape of an app name
// and not be reserved (store.ValidPresenceApp / ReservedPresenceApp — the same check the hub's app record uses); the
// two dates must be times, and the end must be after the press and at most 40 days after it.
func parseReceipt(detailsJSON string) (receipt, bool) {
var d struct {
Subject string `json:"subject"`
StackName string `json:"stack_name"`
RemovedAt string `json:"removed_at"`
EndsAt string `json:"ends_at"`
}
if err := json.Unmarshal([]byte(detailsJSON), &d); err != nil || d.Subject == "" {
return ""
if detailsJSON == "" || json.Unmarshal([]byte(detailsJSON), &d) != nil {
return receipt{}, false
}
return ":" + d.Subject
if !store.ValidPresenceApp(d.StackName) || store.ReservedPresenceApp(d.StackName) {
return receipt{}, false
}
removed, err1 := time.Parse(time.RFC3339, d.RemovedAt)
ends, err2 := time.Parse(time.RFC3339, d.EndsAt)
if err1 != nil || err2 != nil || !ends.After(removed) || ends.Sub(removed) > 40*24*time.Hour {
return receipt{}, false
}
return receipt{App: d.StackName, Removed: removed.UTC(), Ends: ends.UTC()}, true
}
// receiptDate writes a day in the household's date form (the controller's i18n.FormatDate), in Budapest time.
func receiptDate(lang string, t time.Time) string {
if budapest != nil {
t = t.In(budapest)
}
if i18n.Normalize(lang) == "en" {
return t.Format("2006-01-02")
}
return t.Format("2006. 01. 02.")
}
// FormatReceiptEmail is the receipt's whole text — the hub's own words and the checked details, nothing of the box's.
func FormatReceiptEmail(lang, customerID, eventType, severity string, rc receipt) (string, string) {
b := i18n.Shared()
lang = i18n.Normalize(lang)
sentence := b.Msgf(lang, "mail.receipt."+eventType, rc.App, receiptDate(lang, rc.Ends))
// The details the frame reads (the app for the headline) are rebuilt from the CHECKED values.
det, _ := json.Marshal(map[string]string{"stack_name": rc.App})
return FormatCustomerEmail(lang, customerID, eventType, severity, sentence, "", string(det))
}
// processReceipt mails ONE receipt to the household, or drops it — see householdReceiptEvents.
func (d *Dispatcher) processReceipt(customerID, eventType, severity, detailsJSON string) {
rc, ok := parseReceipt(detailsJSON)
if !ok {
d.receiptDropped(customerID, eventType, "its details do not name an app and two dates the hub accepts")
return
}
if d.store.IsCustomerBlocked(customerID) {
return
}
prefs, err := d.store.GetNotificationPrefs(customerID)
if err != nil || prefs == nil || prefs.Email == "" {
return // no address: the page is all the household has
}
key := customerID + ":" + eventType + ":" + rc.App + "|" + rc.Removed.Format(time.RFC3339)
now := time.Now()
sentToday, cerr := d.store.CountCustomerSentSince(customerID, eventType, now.Add(-24*time.Hour))
if cerr != nil {
sentToday = receiptsPerDay // a log that cannot be read is not „nothing sent”: no receipt goes
}
d.mu.Lock()
// The map holds only presses of the last day: older keys of this household's receipts go now.
prefix, inFlight := customerID+":"+eventType+":", 0
for k, at := range d.custCooldowns {
if strings.HasPrefix(k, prefix) {
if now.Sub(at) >= receiptCooldown {
delete(d.custCooldowns, k)
} else {
inFlight++
}
}
}
if _, dup := d.custCooldowns[key]; dup {
d.mu.Unlock()
d.logger.Printf("[INFO] Receipt %s for %s/%s skipped — this press was mailed already", eventType, customerID, rc.App)
return
}
// The limit counts what the log says was sent AND what is reserved in memory (a burst is processed faster than
// the log is written).
if sentToday >= receiptsPerDay || inFlight >= receiptsPerDay {
d.mu.Unlock()
d.receiptDropped(customerID, eventType, fmt.Sprintf("the household already got %d receipt(s) in the last 24 hours (the limit)", receiptsPerDay))
return
}
d.custCooldowns[key] = now
d.mu.Unlock()
subject, body := FormatReceiptEmail(d.store.CustomerLanguage(customerID), customerID, eventType, severity, rc)
logMsg := eventType + " " + rc.App
if err := d.deliver("customer receipt "+eventType, customerID, prefs.Email, subject, body, priorityHeaders(severity)); isHeld(err) {
d.forgetCustomerCooldown(key)
d.store.LogNotification(customerID, eventType, severity, logMsg, "held", "MAIL-HOLD marker present — dropped", "customer")
return
} else if err != nil {
d.logger.Printf("[ERROR] Receipt %s failed for %s: %v", eventType, customerID, err)
d.store.LogNotification(customerID, eventType, severity, logMsg, "failed", err.Error(), "customer")
return
}
d.logger.Printf("[INFO] Receipt %s sent for %s/%s", eventType, customerID, rc.App) // never the address (R-922)
d.store.LogNotification(customerID, eventType, severity, logMsg, "sent", "", "customer")
}
// receiptDropped says ONCE per household and day that receipts are being dropped, and why — in the hub's log and as
// one `skipped` row. A box that posts a thousand of them gets one line, not a thousand.
func (d *Dispatcher) receiptDropped(customerID, eventType, why string) {
day := time.Now().UTC().Format("2006-01-02")
d.mu.Lock()
if d.receiptDropDay == nil {
d.receiptDropDay = map[string]string{}
}
already := d.receiptDropDay[customerID] == day
d.receiptDropDay[customerID] = day
d.mu.Unlock()
if already {
return
}
d.logger.Printf("[WARN] Receipt %s from the box of %s was NOT mailed: %s. Further drops for this household are not logged today.", eventType, customerID, why)
d.store.LogNotification(customerID, eventType, "info", eventType, "skipped", "receipt dropped: "+why, "customer")
}
// operatorOnlyEvents are event types that must NEVER reach a customer, whatever their preferences say.
@@ -1146,9 +1275,8 @@ func (d *Dispatcher) processCustomer(customerID, eventType, severity, message, m
return
}
// Check if event type is enabled. A receipt (D84) is not a detector the household switches: see
// householdReceiptEvents.
if !householdReceiptEvents[eventType] && !isEventEnabled(prefs.EnabledEvents, eventType) {
// Check if event type is enabled
if !isEventEnabled(prefs.EnabledEvents, eventType) {
return
}
@@ -1179,7 +1307,6 @@ func (d *Dispatcher) processCustomer(customerID, eventType, severity, message, m
if perAppCustomerCooldownEvents[eventType] {
cooldownKey += cooldownStackSuffixFor(detailsJSON)
}
cooldownKey += receiptSubjectSuffix(eventType, detailsJSON) // D84: one mail per press
d.mu.Lock()
if last, ok := d.custCooldowns[cooldownKey]; ok && time.Since(last) < cooldownDur {
d.mu.Unlock()
+1 -2
View File
@@ -224,8 +224,7 @@ func FormatCustomerEmail(lang, customerID, eventType, severity, message, message
// operator's mail (FormatOperatorEmail) keeps the note. Pinned by r79_health_mail_test.go.
body += b.Msg(lang, "mail.customer.line.health_dashboard")
} else if householdReceiptEvents[eventType] {
// D84: a receipt's details are the record's own fields (app, dates, the press's key) — the sentence above
// already says them in words; the raw JSON would add nothing a household can read.
// D84: a receipt carries no raw details — the hub's own sentence says them in words (FormatReceiptEmail).
} else if detailsJSON != "" && detailsJSON != "{}" {
body += b.Msgf(lang, "mail.customer.line.note", detailsJSON)
}
+9
View File
@@ -405,3 +405,12 @@ func (s *Store) BackdateOffsiteWindowForTest(id int64, by time.Duration) error {
_, err := s.db.Exec(`UPDATE offsite_windows SET opened_at = ? WHERE id = ?`, time.Now().UTC().Add(-by).Format("2006-01-02 15:04:05"), id)
return err
}
// CountCustomerSentSince counts the mails of one type the hub's own log says were SENT to a household since `since`
// (the receipt's daily limit — it survives a hub restart, which a counter in memory would not).
func (s *Store) CountCustomerSentSince(customerID, eventType string, since time.Time) (int, error) {
var n int
err := s.db.QueryRow(`SELECT COUNT(*) FROM notification_log WHERE customer_id = ? AND event_type = ? AND channel = 'customer' AND status = 'sent' AND created_at >= ?`,
customerID, eventType, since.UTC().Format("2006-01-02 15:04:05")).Scan(&n)
return n, err
}