v0.253.0 — errors carry the key of the sentence they are (R-557 slice 2 release B)

179 Hungarian sentences were built deep inside a package with fmt.Errorf and printed by whoever caught them: too late to translate where they are shown, too early where they are made. Every one now carries its key across that gap. ZERO Hungarian error literals remain. util.MsgError does three things at once, each earned: - Error() is the Hungarian, byte for byte, so every un-converted printer is unchanged; - errors.Is answers for the kind AND for a wrapped cause (KindErrorf dropped the cause); - an error ARGUMENT renders recursively, so "formázás sikertelen: %w" translates whole. A foreign error — restic, docker, ssh, the stdlib — prints verbatim. It is not ours. 76 display sites go through errText, and TestNoErrErrorInPageOutput convicts any that do not. memoryVerdict returns an error rather than a sentence, so the deploy's 409 and the household's language come from one value; UpdateRefusal gained a Cause to carry it. Plurals, one rule, stated once: a key with .one/.other takes its COUNT first. Not a per-call-site flag — the producer somebody forgot would read "3 app is not running". The guard caught a real key collision (alert.deadapp.one) the day the rule landed. TWO DEFECTS FOUND IN MY OWN TOOLING, recorded rather than quietly fixed. The bulk converter silently dropped multi-line concatenations, damaging 7 producers — and the parity gate could not see it, because every surviving fragment WAS a real base literal while the CALL had lost text; two behaviour tests caught it. And the counting script was case-sensitive, so it said "0 left" while five remained. MinAgent: 0.131.0 (unchanged). No hub release needed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS
2026-09-18 11:44:30 +02:00
parent 5270bad76e
commit 7c05b59708
70 changed files with 1853 additions and 377 deletions
@@ -0,0 +1,151 @@
+package util
+
+import (
+	"errors"
+	"fmt"
+	"gitea.dooplex.hu/admin/felhom-controller/internal/i18n"
+)
+
+// ── An error that carries the KEY of the sentence it is, not only the sentence ────────────────────
+//
+// Localisation slice 2 release B (R-557). 179 Hungarian sentences in this product are built deep
+// inside a package with `fmt.Errorf` and printed by whoever catches them — a page, a JSON answer, a
+// flash. They cannot be translated where they are SHOWN, because by then they are a finished string;
+// and they must not be translated where they are MADE, because that code has no request and no
+// language. So the error carries its key and the display end renders it.
+//
+//	return util.MsgErrorf(stacks.ErrRequiredField, "deploy.field_required", label)
+//	...
+//	http.Error(w, s.errText(r, err), 400)     // the household's language
+//	if errors.Is(err, stacks.ErrRequiredField) { … }   // still true — R-553's signal is intact
+//
+// THREE PROPERTIES, each earned:
+//
+//  1. `Error()` RETURNS THE HUNGARIAN TEXT, byte for byte what `fmt.Errorf` produced. Every printer
+//     that has not been converted — a log line, a third-party wrapper, `%v` in a Printf — keeps
+//     printing exactly what it printed before. That is what makes converting 179 producers safe
+//     without converting all their printers in the same commit, and it is what the parity gate
+//     measures.
+//  2. `errors.Is` STILL WORKS, for the kind AND for a wrapped cause. `Unwrap() []error` returns the
+//     kind first and then any error among the arguments, so `errors.Is(err, ErrRequiredField)` and
+//     `errors.Is(err, os.ErrNotExist)` are both answerable. The predecessor `KindErrorf` returned the
+//     kind alone and dropped the cause; this does not.
+//  3. AN ERROR ARGUMENT IS RENDERED RECURSIVELY. `fmt.Errorf("formázás sikertelen: %w", err)` is a
+//     sentence wrapping a sentence. Passing the inner error as an ARGUMENT (not as pre-rendered text)
+//     lets `Text(lang, …)` translate the whole chain — the outer in the household's language and the
+//     inner too, when the inner also carries a key. An inner error with no key prints itself, which
+//     is the right answer for a restic or docker message that is not ours to translate.
+
+// MsgErrorf builds an error whose message is the bundle's `key` filled with `args`.
+//
+// `kind` may be nil. When it is not, it is the sentinel `errors.Is` tests — the same contract
+// KindErrorf established (R-553), and the reason a converted producer does not break a decision.
+func MsgErrorf(kind error, key string, args ...interface{}) error {
+	return &msgError{kind: kind, key: key, args: args}
+}
+
+// MsgError is MsgErrorf with no kind, for a producer nothing branches on.
+func MsgError(key string, args ...interface{}) error {
+	return &msgError{key: key, args: args}
+}
+
+type msgError struct {
+	kind error
+	key  string
+	args []interface{}
+}
+
+// Error returns the Hungarian sentence — the default language, and the bytes the literal carried.
+func (e *msgError) Error() string { return e.Text(i18n.Default) }
+
+// Text renders the message in lang, rendering any error argument that also carries a key.
+func (e *msgError) Text(lang string) string {
+	b, err := i18n.Shared()
+	if err != nil {
+		return e.key
+	}
+	if len(e.args) == 0 {
+		return b.Msg(lang, e.key)
+	}
+	out := make([]interface{}, len(e.args))
+	for i, a := range e.args {
+		if inner, ok := a.(error); ok {
+			out[i] = ErrText(lang, inner)
+			continue
+		}
+		out[i] = a
+	}
+	return b.Msgf(lang, e.key, out...)
+}
+
+// Key returns the bundle key, so a caller can name it without rendering it.
+func (e *msgError) Key() string { return e.key }
+
+// Args returns the message's parameters as strings, for a carrier that can only hold text — the
+// `fa` parameters of a flash in a redirect URL.
+//
+// An ERROR argument is rendered in HUNGARIAN here, deliberately and with a known cost: the carrier is
+// written by one request and read by another, so the writer cannot know the reader's language, and a
+// nested foreign sentence (restic, docker) is not translatable anyway. The OUTER message still
+// follows the reader's language, which is the sentence that carries the meaning.
+func (e *msgError) Args() []string {
+	out := make([]string, 0, len(e.args))
+	for _, a := range e.args {
+		if inner, ok := a.(error); ok {
+			out = append(out, ErrText(i18n.Default, inner))
+			continue
+		}
+		out = append(out, fmt.Sprintf("%v", a))
+	}
+	return out
+}
+
+// Unwrap returns the kind FIRST and then every error among the arguments, so `errors.Is` answers for
+// the decision signal and for the cause alike.
+func (e *msgError) Unwrap() []error {
+	var out []error
+	if e.kind != nil {
+		out = append(out, e.kind)
+	}
+	for _, a := range e.args {
+		if inner, ok := a.(error); ok && inner != nil {
+			out = append(out, inner)
+		}
+	}
+	return out
+}
+
+// Msg is the interface a message-carrying error satisfies. Declared so a caller can test for the
+// capability rather than for this concrete type — the point is "does this error know its key", not
+// "was it built by this constructor".
+type Msg interface {
+	error
+	Text(lang string) string
+	Key() string
+	Args() []string
+}
+
+// AsMsg reports whether err (or anything it wraps) carries a message key, and returns it.
+func AsMsg(err error) (Msg, bool) {
+	var m Msg
+	if errors.As(err, &m) {
+		return m, true
+	}
+	return nil, false
+}
+
+// ErrText is the one function every display end calls: the error's sentence in lang.
+//
+// An error that carries a key is rendered in lang. **Anything else is returned verbatim** — a restic
+// message, a docker message, an ssh message, a Go stdlib error. That is not a gap: those sentences
+// are not written here and are not translated here (10-localisation.md §9, the rule R-553
+// established). A customer seeing restic's own English is seeing what restic said.
+func ErrText(lang string, err error) string {
+	if err == nil {
+		return ""
+	}
+	if m, ok := AsMsg(err); ok {
+		return m.Text(lang)
+	}
+	return err.Error()
+}
@@ -0,0 +1,139 @@
+package util
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-controller/internal/i18n"
+)
+
+// Localisation slice 2 release B (R-557), scenarios S3 and its wrong case.
+//
+// A message-carrying error has to do three things at once, and each one is a different failure if it
+// is missing: print the Hungarian it always printed (parity), still satisfy the decision a caller
+// makes on it (R-553), and render in the reader's language at the display end (the point).
+
+// a real key from the bundle, with one parameter, so nothing here is a fixture of itself
+const oneParamKey = "flash.offbox.config_invalid"
+
+var errTestKind = errors.New("test-kind")
+
+func TestMsgErrorKeepsKindAndHuText(t *testing.T) {
+	b, err := i18n.Load()
+	if err != nil {
+		t.Fatal(err)
+	}
+	e := MsgErrorf(errTestKind, oneParamKey, "a port nem szam")
+
+	// 1. parity: Error() is the Hungarian sentence, byte for byte what fmt.Errorf produced.
+	want := fmt.Sprintf(b.Msg(i18n.Default, oneParamKey), "a port nem szam")
+	if e.Error() != want {
+		t.Errorf("Error() is not the Hungarian sentence\n  got  %q\n  want %q", e.Error(), want)
+	}
+	// And an un-converted printer — a log line, a %v — sees exactly that.
+	if got := fmt.Sprintf("%v", e); got != want {
+		t.Errorf("%%v printed %q, want %q", got, want)
+	}
+
+	// 2. the decision still reads: R-553's whole point.
+	if !errors.Is(e, errTestKind) {
+		t.Error("errors.Is no longer finds the kind — every status-code decision built on R-553 breaks")
+	}
+	if errors.Is(e, os.ErrNotExist) {
+		t.Error("errors.Is matched an unrelated sentinel")
+	}
+
+	// 3. the display end renders in the reader's language.
+	if en := ErrText("en", e); en == want || en == "" {
+		t.Errorf("English render did not happen: %q", en)
+	}
+	if hu := ErrText(i18n.Default, e); hu != want {
+		t.Errorf("Hungarian render moved:\n  got  %q\n  want %q", hu, want)
+	}
+}
+
+// TestMsgErrorUnwrapsTheCauseToo — the predecessor (KindErrorf) returned the kind ALONE from Unwrap,
+// so a wrapped cause was unreachable. A converted producer often wraps one (`%w` on an os or docker
+// error), and a caller that tested for it would have silently stopped matching.
+func TestMsgErrorUnwrapsTheCauseToo(t *testing.T) {
+	cause := fmt.Errorf("open /x: %w", os.ErrNotExist)
+	e := MsgErrorf(errTestKind, oneParamKey, cause)
+
+	if !errors.Is(e, errTestKind) {
+		t.Error("the kind is unreachable")
+	}
+	if !errors.Is(e, os.ErrNotExist) {
+		t.Error("the wrapped CAUSE is unreachable — this is what KindErrorf lost")
+	}
+}
+
+func TestErrTextFallsBackVerbatim(t *testing.T) {
+	// The wrong case in S3: an error from restic, docker, ssh or the stdlib is not ours to translate.
+	for _, e := range []error{
+		errors.New("repository is already locked by PID 1234"),
+		fmt.Errorf("Error response from daemon: No such container: x"),
+		os.ErrPermission,
+	} {
+		for _, lang := range []string{"hu", "en"} {
+			if got := ErrText(lang, e); got != e.Error() {
+				t.Errorf("%s: a foreign error was rewritten\n  got  %q\n  want %q", lang, got, e.Error())
+			}
+		}
+	}
+	if got := ErrText("en", nil); got != "" {
+		t.Errorf("a nil error must render empty, got %q", got)
+	}
+}
+
+// TestErrTextRendersAWrappedMessageErrorToo — a sentence wrapping a sentence. Both halves are ours,
+// so BOTH follow the language; that only works because the inner error is passed as an ARGUMENT
+// rather than as pre-rendered text.
+func TestErrTextRendersAWrappedMessageErrorToo(t *testing.T) {
+	inner := MsgError("flash.offbox.app_missing")
+	outer := MsgError(oneParamKey, inner)
+
+	hu, en := ErrText("hu", outer), ErrText("en", outer)
+	if hu == en {
+		t.Fatalf("the wrapped chain did not follow the language at all: %q", hu)
+	}
+	b, _ := i18n.Load()
+	if innerHU := b.Msg("hu", "flash.offbox.app_missing"); !contains(hu, innerHU) {
+		t.Errorf("the Hungarian render lost the inner sentence\n  got %q\n  want it to contain %q", hu, innerHU)
+	}
+	if innerEN := b.Msg("en", "flash.offbox.app_missing"); !contains(en, innerEN) {
+		t.Errorf("the English render kept the Hungarian inner sentence\n  got %q\n  want it to contain %q", en, innerEN)
+	}
+}
+
+// TestAsMsgSeesThroughAFmtWrapper — a converted error that something else wrapped with `%w` still
+// answers AsMsg, so a printer further out does not lose the key.
+func TestAsMsgSeesThroughAFmtWrapper(t *testing.T) {
+	e := fmt.Errorf("context: %w", MsgError("flash.offbox.app_missing"))
+	m, ok := AsMsg(e)
+	if !ok {
+		t.Fatal("AsMsg lost the key through a fmt wrapper")
+	}
+	if m.Key() != "flash.offbox.app_missing" {
+		t.Errorf("wrong key: %q", m.Key())
+	}
+	// The OUTER text is fmt's, and it is what a caller printing the whole chain sees — errText
+	// renders the innermost message it can find, which is the sentence a customer needs. Stated so
+	// nobody reads this as the outer text being dropped by accident: a `%w` wrapper that adds
+	// Hungarian of its own should itself be a MsgError, and release B converts those.
+	if ErrText("en", e) == e.Error() {
+		t.Error("the English render was identical to the Hungarian chain")
+	}
+}
+
+func contains(s, sub string) bool {
+	return len(sub) > 0 && len(s) >= len(sub) && (func() bool {
+		for i := 0; i+len(sub) <= len(s); i++ {
+			if s[i:i+len(sub)] == sub {
+				return true
+			}
+		}
+		return false
+	})()
+}