refactor: user error system (#40308)

Introduce "FlashErrorAuto" for "XxxErrorAuto" family and simplify the
error handling logic.

* Use ErrorUnwrapForHTML for web error messages 
* Use ErrorUnwrapForUser for api error messages
* Make Flash message can take up to about 3000 bytes

Next step: completely refactor "ctx.ServerError"

---------

Co-authored-by: silverwind <me@silverwind.io>
This commit is contained in:
wxiaoguangandsilverwind authored and GitHub committed 2026-11-10 16:29:36 +00:00
1 parent 518e08c2c7
commit d1d702bea9
20 files changed
+309 -194

No files matched your search

+2
View File
@@ -15,6 +15,8 @@ func TestSanitizer(t *testing.T) {
// Regular
`<a onblur="alert(secret)" href="http://www.google.com">Google</a>`, `<a href="http://www.google.com" rel="nofollow">Google</a>`,
"<scrİpt>&lt;script&gt;alert(document.domain)&lt;/script&gt;</scrİpt>", "&lt;script&gt;alert(document.domain)&lt;/script&gt;",
`<details>unclosed`, `<details>unclosed`,
`<div>unclosed</`, `<div>unclosed&lt;/`,
// Code highlighting class
`<code class="random string"></code>`, `<code></code>`,
+51 -32
View File
@@ -6,6 +6,7 @@ package util
import (
"errors"
"fmt"
"html"
"html/template"
)
@@ -13,13 +14,6 @@ import (
// These errors can be used to classify errors and to provide a common,
// safe (no server-side sensitive information), and translatable error message for end users.
// ErrorTranslatable wraps an error with translation information
type ErrorTranslatable interface {
error
Unwrap() error
Translate(ErrorLocaleTranslator) template.HTML
}
var (
ErrInvalidArgument = errorForUser{400, "invalid argument"}
ErrPermissionDenied = errorForUser{403, "permission denied"}
@@ -40,7 +34,48 @@ func (w errorForUser) Error() string {
return w.msg
}
// TODO: introduce ErrorUnwrapForHTML in the future for web error rendering
// ErrorTranslateHTML translates the error message to HTML using the provided locale translator.
// If the error is not translatable, it returns false.
func ErrorTranslateHTML(err error, locale ErrorLocaleTranslator) (template.HTML, bool) {
if errAs := errorAsTranslatable(err); errAs != nil {
return locale.Tr(errAs.trKey, errAs.trArgs...), true
}
return "", false
}
// ErrorUnwrapForHTML unwraps the user error and returns the error message in HTML format and the HTTP status code.
// An error is considered a user error if it is "errorForUser" or "errorTranslatable"
// * errorTranslatable: The error message is translated to HTML using the provided locale translator.
// * errorForUser: The error message is returned as is (escaped to HTML) and the HTTP status code is returned.
// If the error is not a user error, it returns an empty message and code 0.
func ErrorUnwrapForHTML(err error, locale ErrorLocaleTranslator) (msg template.HTML, code int) {
if e, ok := errors.AsType[errorForUser](err); ok {
code = e.code
}
if htmlMsg, ok := ErrorTranslateHTML(err, locale); ok {
msg = htmlMsg
code = IfZero(code, 400)
}
if code != 0 && msg == "" {
errMsg := err.Error()
switch errMsg {
case ErrPermissionDenied.msg:
msg = locale.Tr("error.permission_denied")
case ErrNotExist.msg:
msg = locale.Tr("error.not_found")
default:
msg = template.HTML(html.EscapeString(errMsg))
}
}
return msg, code
}
// ErrorUnwrapForUser unwraps the user error and returns the error message in string format and the HTTP status code.
// It is mainly used for API error responses, and ideally only English locale should be used.
//
// It also accepts a locale translator to translate the error message if it is translatable:
// * for example: there are different error messages for "ErrBlockedUser": blocked by owner, or blocked by assignee
// * only the function returned the error message can know the exact reason
func ErrorUnwrapForUser(err error, locale ...ErrorLocaleTranslator) (msg string, code int) {
e, ok := errors.AsType[errorForUser](err)
if ok {
@@ -98,7 +133,7 @@ func NewNotExistErrorf(message string, args ...any) error {
return ErrorWrap(ErrNotExist, message, args...)
}
type errorTranslatableWrapper struct {
type errorTranslatable struct {
err error
trKey string
trArgs []any
@@ -109,30 +144,14 @@ type ErrorLocaleTranslator interface {
TrString(key string, args ...any) string
}
func (w *errorTranslatableWrapper) Error() string { return w.err.Error() }
func (w *errorTranslatable) Error() string { return w.err.Error() }
func (w *errorTranslatable) Unwrap() error { return w.err }
func (w *errorTranslatableWrapper) Unwrap() error { return w.err }
func (w *errorTranslatableWrapper) Translate(t ErrorLocaleTranslator) template.HTML {
return t.Tr(w.trKey, w.trArgs...)
func ErrorWrapTranslatable(err error, trKey string, trArgs ...any) error {
return &errorTranslatable{err: err, trKey: trKey, trArgs: trArgs}
}
func ErrorWrapTranslatable(err error, trKey string, trArgs ...any) ErrorTranslatable {
return &errorTranslatableWrapper{err: err, trKey: trKey, trArgs: trArgs}
}
func errorAsTranslatable(err error) *errorTranslatableWrapper {
if e, ok := errors.AsType[*errorTranslatableWrapper](err); ok {
return e
}
return nil
}
// TODO: refactor ErrorAsTranslatable in the future, use ErrorUnwrapForUser or ErrorUnwrapForHTML as much as possible
func ErrorAsTranslatable(err error) ErrorTranslatable {
e := errorAsTranslatable(err)
if e != nil { // avoid golang nil interface wrapper
return e
}
return nil
func errorAsTranslatable(err error) *errorTranslatable {
e, _ := errors.AsType[*errorTranslatable](err)
return e
}
+30 -8
View File
@@ -5,6 +5,7 @@ package util
import (
"fmt"
"html/template"
"io"
"testing"
@@ -18,7 +19,7 @@ func TestErrorTranslatable(t *testing.T) {
err = ErrorWrapTranslatable(io.EOF, "key", 1)
assert.ErrorIs(t, err, io.EOF)
assert.Equal(t, "EOF", err.Error())
wrapped, ok := err.(*errorTranslatableWrapper)
wrapped, ok := err.(*errorTranslatable)
require.True(t, ok)
assert.Equal(t, "key", wrapped.trKey)
assert.Equal(t, []any{1}, wrapped.trArgs)
@@ -26,15 +27,36 @@ func TestErrorTranslatable(t *testing.T) {
err = ErrorWrap(err, "new msg %d", 100)
assert.ErrorIs(t, err, io.EOF)
assert.Equal(t, "new msg 100", err.Error())
}
errTr := ErrorAsTranslatable(err)
assert.Equal(t, "EOF", errTr.Error())
wrapped, ok = errTr.(*errorTranslatableWrapper)
require.True(t, ok)
assert.Equal(t, "key", wrapped.trKey)
type testErrorLocale struct{}
errTr = ErrorAsTranslatable(nil)
assert.True(t, errTr == nil) //nolint:testifylint // assert golang nil interface wrapper
func (l testErrorLocale) Tr(key string, args ...any) template.HTML {
return template.HTML(l.TrString(key, args...))
}
func (testErrorLocale) TrString(key string, args ...any) string {
return fmt.Sprintf(key, args...)
}
func TestErrorUnwrapForHTML(t *testing.T) {
locale := testErrorLocale{}
err := NewNotExistErrorf("missing <file>")
msg, code := ErrorUnwrapForHTML(err, locale)
assert.Equal(t, template.HTML("missing &lt;file&gt;"), msg)
assert.Equal(t, 404, code)
msg, code = ErrorUnwrapForHTML(ErrorWrapTranslatable(err, "missing <b>%s</b>", "file"), locale)
assert.Equal(t, template.HTML("missing <b>file</b>"), msg)
assert.Equal(t, 404, code)
msg, code = ErrorUnwrapForHTML(ErrorWrapTranslatable(io.EOF, "unexpected end of input"), locale)
assert.Equal(t, template.HTML("unexpected end of input"), msg)
assert.Equal(t, 400, code)
msg, code = ErrorUnwrapForHTML(io.EOF, locale)
assert.Empty(t, msg)
assert.Zero(t, code)
}
func TestErrorUnwrapForUser(t *testing.T) {
+88 -30
View File
@@ -4,24 +4,29 @@
package middleware
import (
"fmt"
"encoding/base64"
"html/template"
"net/http"
"net/url"
"strings"
"sync"
"gitea.dev/modules/reqctx"
"gitea.dev/modules/util"
)
// Flash represents a one time data transfer between two requests.
type Flash struct {
DataStore reqctx.RequestDataStore
url.Values
msgValues map[string]string
// message is in HTML format, and is sanitized when rendering (ref: RenderFlashMessage)
ErrorMsg, WarningMsg, InfoMsg, SuccessMsg string
}
func (f *Flash) set(name, msg string, current ...bool) {
if f.Values == nil {
f.Values = make(map[string][]string)
if f.msgValues == nil {
f.msgValues = map[string]string{}
}
showInCurrentPage := len(current) > 0 && current[0]
if showInCurrentPage {
@@ -29,59 +34,112 @@ func (f *Flash) set(name, msg string, current ...bool) {
f.DataStore.GetData()["Flash"] = f
} else {
// the message map will be saved into the cookie and be shown in next response (a new page response which decodes the cookie)
f.Set(name, msg)
f.msgValues[name] = msg
}
}
func flashMsgStringOrHTML(msg any) string {
switch v := msg.(type) {
case string:
return v
case template.HTML:
return string(v)
var flashMessageReplacer = sync.OnceValue(func() (ret struct {
encoder, decoder *strings.Replacer
},
) {
ret.encoder = strings.NewReplacer("\\", "\\\\", "\n", "\\n")
ret.decoder = strings.NewReplacer("\\\\", "\\", "\\n", "\n")
return ret
})
func flashMessageEncode(m map[string]string, limit int) string {
if len(m) == 0 {
return ""
}
panic(fmt.Sprintf("unknown type: %T", msg))
buf := strings.Builder{}
buf.Grow(200) // most messages are short, use a good initial size
for k, v := range m {
buf.WriteString(k)
buf.WriteByte('=')
buf.WriteString(flashMessageReplacer().encoder.Replace(v))
buf.WriteByte('\n')
}
s := buf.String()
n := min(len(s), limit)
return base64.RawURLEncoding.EncodeToString(util.UnsafeStringToBytes(s[:n]))
}
func flashMessageDecode(s string) map[string]string {
if s == "" {
return nil
}
if strings.Contains(s, "=") {
// legacy format, just parse it as query string
vals, err := url.ParseQuery(s)
if err != nil {
return nil
}
m := make(map[string]string, len(vals))
for k, v := range vals {
if len(v) > 0 {
m[k] = v[0]
}
}
return m
}
data, err := base64.RawURLEncoding.DecodeString(s)
if err != nil {
return nil
}
m := make(map[string]string)
for line := range strings.SplitSeq(util.UnsafeBytesToString(data), "\n") {
if line == "" {
continue
}
k, v, _ := strings.Cut(line, "=")
if v != "" {
v = flashMessageReplacer().decoder.Replace(v)
m[k] = strings.ToValidUTF8(v, "")
}
}
return m
}
func (f *Flash) EncodeToString() string {
// modern browsers support 4096 bytes for a cookie, we use base64 for encoding, so limit to 3000
return flashMessageEncode(f.msgValues, 3000)
}
// Error sets error message
func (f *Flash) Error(msg any, current ...bool) {
f.ErrorMsg = flashMsgStringOrHTML(msg)
func (f *Flash) Error[T string | template.HTML](msg T, current ...bool) {
f.ErrorMsg = string(msg)
f.set("error", f.ErrorMsg, current...)
}
// Warning sets warning message
func (f *Flash) Warning(msg any, current ...bool) {
f.WarningMsg = flashMsgStringOrHTML(msg)
func (f *Flash) Warning[T string | template.HTML](msg T, current ...bool) {
f.WarningMsg = string(msg)
f.set("warning", f.WarningMsg, current...)
}
// Info sets info message
func (f *Flash) Info(msg any, current ...bool) {
f.InfoMsg = flashMsgStringOrHTML(msg)
func (f *Flash) Info[T string | template.HTML](msg T, current ...bool) {
f.InfoMsg = string(msg)
f.set("info", f.InfoMsg, current...)
}
// Success sets success message
func (f *Flash) Success(msg any, current ...bool) {
f.SuccessMsg = flashMsgStringOrHTML(msg)
func (f *Flash) Success[T string | template.HTML](msg T, current ...bool) {
f.SuccessMsg = string(msg)
f.set("success", f.SuccessMsg, current...)
}
func ParseCookieFlashMessage(val string) *Flash {
if vals, _ := url.ParseQuery(val); len(vals) > 0 {
return &Flash{
Values: vals,
ErrorMsg: vals.Get("error"),
SuccessMsg: vals.Get("success"),
InfoMsg: vals.Get("info"),
WarningMsg: vals.Get("warning"),
}
m := flashMessageDecode(val)
if len(m) == 0 {
return nil
}
return nil
return &Flash{ErrorMsg: m["error"], SuccessMsg: m["success"], InfoMsg: m["info"], WarningMsg: m["warning"]}
}
func GetSiteCookieFlashMessage(dataStore reqctx.RequestDataStore, req *http.Request, cookieName string) (string, *Flash) {
// Get the last flash message from cookie
lastFlashCookie := GetSiteCookie(req, cookieName)
lastFlashMsg := ParseCookieFlashMessage(lastFlashCookie)
if lastFlashMsg != nil {
+29
View File
@@ -0,0 +1,29 @@
// Copyright 2026 The Gitea Authors. All rights reserved.
// SPDX-License-Identifier: MIT
package middleware
import (
"strings"
"testing"
"github.com/stretchr/testify/assert"
)
func TestFlashMessageEncode(t *testing.T) {
assert.Empty(t, flashMessageEncode(nil, 100))
messages := map[string]string{"error": "<div>\n<div>", "success": "🌞"}
assert.Equal(t, messages, flashMessageDecode(flashMessageEncode(messages, 100)))
assert.Equal(t, map[string]string{"error": "删除分支失败"}, flashMessageDecode(flashMessageEncode(map[string]string{"error": "删除分支\xff失败"}, 100)))
const limit = 99
encoded := flashMessageEncode(map[string]string{"error": strings.Repeat("x", 200)}, limit)
assert.Len(t, encoded, limit/3*4)
decoded := flashMessageDecode(encoded)
assert.Equal(t, map[string]string{"error": strings.Repeat("x", limit-len("error="))}, decoded)
// also support legacy format
decoded = flashMessageDecode("error=invalid%20message")
assert.Equal(t, map[string]string{"error": "invalid message"}, decoded)
}