feat: SEO backend data (1/4)

internal/domain/article/articleDomain.go

@@ -2,7 +2,11 @@ package article
 
 import (
 	"RenewCMS/internal/domain/author"
+	"RenewCMS/internal/domain/slug"
 	"errors"
+	"net/url"
+	"slices"
+	"strconv"
 	"time"
 	"unicode/utf8"
 )
@@ -11,13 +15,95 @@ var (
 	ErrInvalidTitle    = errors.New("article's title length should be between 3 and 200 caracters")
 	ErrArticleNotFound = errors.New("article not found")
 	ErrArticleOffline  = errors.New("article is offline")
+
+	ErrInvalidSlug         = errors.New("invalid slug")
+	ErrSlugTaken           = errors.New("another article on this site already uses that slug")
+	ErrInvalidCanonicalURL = errors.New("invalid canonical url")
 )
 
+type SlugTakenError struct {
+	Suggestion string
+}
+
+func (e *SlugTakenError) Error() string {
+	return ErrSlugTaken.Error()
+}
+
+func (e *SlugTakenError) Is(target error) bool {
+	return target == ErrSlugTaken
+}
+
 const (
 	MinTitleRunes = 3
 	MaxTitleRunes = 200
+
+	MaxCanonicalURLRunes = 2048
+
+	FallbackSlug = "article"
+	DeletedSlug  = "#deleted-"
+
+	DismissTitleLong  = "title_long"
+	DismissTitleEmpty = "title_empty"
+	DismissDescShort  = "desc_short"
+	DismissDescLong   = "desc_long"
+	DismissCoverAlt   = "cover_alt"
+	DismissCoverNone  = "cover_none"
+	DismissSlugLong   = "slug_long"
+	DismissNoAuthor   = "no_au"
+	DismissNoHeading  = "no_h"
+	DismissBodyAlt    = "body_alt"
+	DismissShort      = "short"
 )
 
+var dismissCodes = []string{
+	DismissTitleLong, DismissTitleEmpty, DismissDescShort, DismissDescLong, DismissCoverAlt, DismissCoverNone,
+	DismissSlugLong, DismissNoAuthor, DismissNoHeading, DismissBodyAlt, DismissShort,
+}
+
+func DismissCodes() []string {
+	return slices.Clone(dismissCodes)
+}
+
+func NormalizeDismissed(codes []string) []string {
+	normalized := make([]string, 0, len(codes))
+	for _, code := range codes {
+		if !slices.Contains(normalized, code) {
+			normalized = append(normalized, code)
+		}
+	}
+	return normalized
+}
+
+func IsValidSlug(candidate string) bool {
+	return slug.IsValid(candidate)
+}
+
+func Tombstone(id uint32) string {
+	return DeletedSlug + strconv.FormatUint(uint64(id), 10)
+}
+
+func GenerateSlug(title string) string {
+	return slug.Generate(title, FallbackSlug)
+}
+
+func SlugWithSuffix(base string, attempt int) string {
+	return slug.WithSuffix(base, attempt)
+}
+
+func ValidateCanonicalURL(raw string) error {
+	if raw == "" {
+		return nil
+	}
+	if utf8.RuneCountInString(raw) > MaxCanonicalURLRunes {
+		return ErrInvalidCanonicalURL
+	}
+	parsed, err := url.Parse(raw)
+	if err != nil || parsed.Scheme != "https" || parsed.Hostname() == "" {
+		return ErrInvalidCanonicalURL
+	}
+	return nil
+}
+
 func ValidateTitle(title string) error {
 	runeCount := utf8.RuneCountInString(title)
 	if runeCount < MinTitleRunes || runeCount > MaxTitleRunes {
@@ -27,12 +113,28 @@ func ValidateTitle(title string) error {
 }
 
 type Article struct {
-	ID        uint32          `json:"id"`
-	Title     string          `json:"title"`
-	Body      string          `json:"body"`
-	IsOnline  bool            `json:"is_online"`
-	SiteID    uint32          `json:"site_id"`
-	Authors   []author.Byline `json:"authors"`
-	CreatedAt time.Time       `json:"created_at"`
-	UpdatedAt time.Time       `json:"updated_at"`
+	ID                uint32          `json:"id"`
+	Title             string          `json:"title"`
+	Body              string          `json:"body"`
+	IsOnline          bool            `json:"is_online"`
+	SiteID            uint32          `json:"site_id"`
+	Authors           []author.Byline `json:"authors"`
+	Slug              string          `json:"slug"`
+	Excerpt           string          `json:"excerpt"`
+	SEOTitle          string          `json:"seo_title"`
+	SEODescription    string          `json:"seo_description"`
+	CoverImageID      *uint32         `json:"cover_image_id"`
+	CoverImageAlt     string          `json:"cover_image_alt"`
+	SocialTitle       string          `json:"social_title"`
+	SocialDescription string          `json:"social_description"`
+	SocialImageID     *uint32         `json:"social_image_id"`
+	CanonicalURL      string          `json:"canonical_url"`
+	Noindex           bool            `json:"noindex"`
+	SEODismissed      []string        `json:"seo_dismissed"`
+	CreatedAt         time.Time       `json:"created_at"`
+	UpdatedAt         time.Time       `json:"updated_at"`
+}
+
+func (a Article) UsesImage(imageID uint32) bool {
+	return a.CoverImageID != nil && *a.CoverImageID == imageID || a.SocialImageID != nil && *a.SocialImageID == imageID
 }

internal/domain/article/articleRepositoryInterface.go

@@ -38,10 +38,36 @@ type Filters struct {
 	Sort     Sort
 }
 
+type Nullable[T any] struct {
+	Set   bool
+	Value *T
+}
+
 type Update struct {
-	Body      *string
-	SiteID    *uint32
-	AuthorIDs *[]uint32
+	Body              *string
+	SiteID            *uint32
+	AuthorIDs         *[]uint32
+	Slug              *string
+	Excerpt           *string
+	SEOTitle          *string
+	SEODescription    *string
+	CoverImageID      Nullable[uint32]
+	CoverImageAlt     *string
+	SocialTitle       *string
+	SocialDescription *string
+	SocialImageID     Nullable[uint32]
+	CanonicalURL      *string
+	Noindex           *bool
+	SEODismissed      *[]string
+}
+
+type ImageReferences struct {
+	Cover  []uint32
+	Social []uint32
+}
+
+func (r ImageReferences) Empty() bool {
+	return len(r.Cover) == 0 && len(r.Social) == 0
 }
 
 type Counts struct {
@@ -68,4 +94,9 @@ type Repository interface {
 	UpdateIsOnline(id uint32, isOnline bool) (Article, error)
 	Delete(id uint32) error
 	FindByBodyContaining(filename string) ([]Article, error)
+	FindByImage(imageID uint32) ([]Article, error)
+	SlugTaken(siteID uint32, slug string, exceptID uint32) (bool, error)
+	ClearImage(imageID uint32) (ImageReferences, error)
+	RestoreImage(references ImageReferences, imageID uint32) error
+	RepointImage(fromImageIDs []uint32, toImageID uint32) ([]uint32, error)
 }

internal/domain/audit/auditChanges.go

@@ -12,8 +12,33 @@ func TextChange(field string, before string, after string) Change {
 }
 
 func BodyChange(before string, after string) Change {
+	return SizeChange(FieldBody, before, after)
+}
+
+func SizeChange(field string, before string, after string) Change {
 	delta := utf8.RuneCountInString(after) - utf8.RuneCountInString(before)
-	return Change{Field: FieldBody, Kind: ChangeBody, Delta: &delta}
+	return Change{Field: field, Kind: ChangeBody, Delta: &delta}
+}
+
+func appendSizeChange(changes []Change, field string, before string, after string) []Change {
+	if before == after {
+		return changes
+	}
+	return append(changes, SizeChange(field, before, after))
+}
+
+func SEOChanges(before article.Article, after article.Article) []Change {
+	changes := []Change{}
+	changes = AppendTextChange(changes, FieldSlug, before.Slug, after.Slug)
+	changes = AppendTextChange(changes, FieldCanonicalURL, before.CanonicalURL, after.CanonicalURL)
+	changes = AppendTextChange(changes, FieldNoindex, strconv.FormatBool(before.Noindex), strconv.FormatBool(after.Noindex))
+	changes = appendSizeChange(changes, FieldExcerpt, before.Excerpt, after.Excerpt)
+	changes = appendSizeChange(changes, FieldSEOTitle, before.SEOTitle, after.SEOTitle)
+	changes = appendSizeChange(changes, FieldSEODescription, before.SEODescription, after.SEODescription)
+	changes = appendSizeChange(changes, FieldCoverImageAlt, before.CoverImageAlt, after.CoverImageAlt)
+	changes = appendSizeChange(changes, FieldSocialTitle, before.SocialTitle, after.SocialTitle)
+	changes = appendSizeChange(changes, FieldSocialDescription, before.SocialDescription, after.SocialDescription)
+	return changes
 }
 
 func ArticleChanges(before article.Article, after article.Article) []Change {
@@ -32,15 +57,15 @@ func ArticleChanges(before article.Article, after article.Article) []Change {
 
 func VariantChanges(before image.VariantSettings, after image.VariantSettings) []Change {
 	changes := []Change{}
-	changes = appendChange(changes, FieldWidth, image.DimensionText(before.Width), image.DimensionText(after.Width))
-	changes = appendChange(changes, FieldHeight, image.DimensionText(before.Height), image.DimensionText(after.Height))
-	changes = appendChange(changes, FieldFit, string(before.Fit), string(after.Fit))
-	changes = appendChange(changes, FieldFormat, string(before.Format), string(after.Format))
-	changes = appendChange(changes, FieldQuality, image.QualityText(before.Quality), image.QualityText(after.Quality))
+	changes = AppendTextChange(changes, FieldWidth, image.DimensionText(before.Width), image.DimensionText(after.Width))
+	changes = AppendTextChange(changes, FieldHeight, image.DimensionText(before.Height), image.DimensionText(after.Height))
+	changes = AppendTextChange(changes, FieldFit, string(before.Fit), string(after.Fit))
+	changes = AppendTextChange(changes, FieldFormat, string(before.Format), string(after.Format))
+	changes = AppendTextChange(changes, FieldQuality, image.QualityText(before.Quality), image.QualityText(after.Quality))
 	return changes
 }
 
-func appendChange(changes []Change, field string, before string, after string) []Change {
+func AppendTextChange(changes []Change, field string, before string, after string) []Change {
 	if before == after {
 		return changes
 	}

internal/domain/audit/auditDomain.go

@@ -121,58 +121,71 @@ const (
 )
 
 const (
-	SystemActorName      = "System"
-	ReasonWrongLogin     = "Wrong username or password."
-	MaxUserAgentLength   = 255
-	ParamRemoved         = "removed"
-	ParamFrom            = "from"
-	ParamTo              = "to"
-	ParamMaxGBFrom       = "max_gb_from"
-	ParamMaxGBTo         = "max_gb_to"
-	ParamMerged          = "merged"
-	ParamArticlesUpdated = "articles_updated"
-	ParamFailedGroups    = "failed_groups"
-	ParamUpdateAvailable = "update_available"
-	ParamKind            = "kind"
-	ParamPurgedFiles     = "purged_files"
-	ParamPurgedBytes     = "purged_bytes"
-	ParamFailedFiles     = "failed_files"
-	ParamOlderThanDays   = "older_than_days"
-	ParamGenerated       = "generated"
-	ParamFailed          = "failed"
-	ParamCauses          = "causes"
-	ParamWidth           = "width"
-	ParamHeight          = "height"
-	ParamFit             = "fit"
-	ParamFormat          = "format"
-	ParamQuality         = "quality"
-	ParamTag             = "tag"
-	FieldTitle           = "title"
-	FieldOnline          = "online"
-	FieldBody            = "body"
-	FieldFilename        = "filename"
-	FieldDisplayName     = "display_name"
-	FieldWidth           = "width"
-	FieldHeight          = "height"
-	FieldFit             = "fit"
-	FieldFormat          = "format"
-	FieldQuality         = "quality"
-	FieldName            = "name"
-	FieldBaseURL         = "base_url"
-	FieldDefaultRobots   = "default_robots"
-	FieldLocale          = "locale"
-	FieldSocialImage     = "default_social_image"
-	FieldSite            = "site"
-	FieldSlug            = "slug"
-	FieldBio             = "bio"
-	FieldWebsite         = "website"
-	FieldSocialLinks     = "social_links"
-	FieldAvatar          = "avatar"
-	FieldUser            = "user"
-	FieldAuthors         = "authors"
-	maxNameLength        = 255
-	maxActionLength      = 64
-	maxFailureReasonSize = 255
+	SystemActorName         = "System"
+	ReasonWrongLogin        = "Wrong username or password."
+	MaxUserAgentLength      = 255
+	ParamRemoved            = "removed"
+	ParamFrom               = "from"
+	ParamTo                 = "to"
+	ParamMaxGBFrom          = "max_gb_from"
+	ParamMaxGBTo            = "max_gb_to"
+	ParamMerged             = "merged"
+	ParamArticlesUpdated    = "articles_updated"
+	ParamFailedGroups       = "failed_groups"
+	ParamUpdateAvailable    = "update_available"
+	ParamKind               = "kind"
+	ParamPurgedFiles        = "purged_files"
+	ParamPurgedBytes        = "purged_bytes"
+	ParamFailedFiles        = "failed_files"
+	ParamOlderThanDays      = "older_than_days"
+	ParamGenerated          = "generated"
+	ParamFailed             = "failed"
+	ParamCauses             = "causes"
+	ParamWidth              = "width"
+	ParamHeight             = "height"
+	ParamFit                = "fit"
+	ParamFormat             = "format"
+	ParamQuality            = "quality"
+	ParamTag                = "tag"
+	FieldTitle              = "title"
+	FieldOnline             = "online"
+	FieldBody               = "body"
+	FieldFilename           = "filename"
+	FieldDisplayName        = "display_name"
+	FieldWidth              = "width"
+	FieldHeight             = "height"
+	FieldFit                = "fit"
+	FieldFormat             = "format"
+	FieldQuality            = "quality"
+	FieldName               = "name"
+	FieldBaseURL            = "base_url"
+	FieldDefaultRobots      = "default_robots"
+	FieldLocale             = "locale"
+	FieldSocialImage        = "default_social_image"
+	FieldSite               = "site"
+	FieldSlug               = "slug"
+	FieldBio                = "bio"
+	FieldWebsite            = "website"
+	FieldSocialLinks        = "social_links"
+	FieldAvatar             = "avatar"
+	FieldUser               = "user"
+	FieldAuthors            = "authors"
+	FieldCanonicalURL       = "canonical_url"
+	FieldNoindex            = "noindex"
+	FieldCoverImage         = "cover_image"
+	FieldArticleSocialImage = "social_image"
+	FieldExcerpt            = "excerpt"
+	FieldSEOTitle           = "seo_title"
+	FieldSEODescription     = "seo_description"
+	FieldSocialTitle        = "social_title"
+	FieldSocialDescription  = "social_description"
+	FieldCoverImageAlt      = "cover_image_alt"
+	FieldSiteName           = "site_name"
+	FieldTitleTemplate      = "title_template"
+	FieldDefaultDescription = "default_description"
+	maxNameLength           = 255
+	maxActionLength         = 64
+	maxFailureReasonSize    = 255
 )
 
 func ActorTypes() []ActorType {

internal/domain/author/authorDomain.go

@@ -1,10 +1,9 @@
 package author
 
 import (
+	"RenewCMS/internal/domain/slug"
 	"errors"
 	"net/url"
-	"regexp"
-	"strconv"
 	"strings"
 	"unicode/utf8"
 )
@@ -41,31 +40,6 @@ const (
 	SocialCustom   = "custom"
 )
 
-var slugPattern = regexp.MustCompile(`^[a-z0-9]+(-[a-z0-9]+)*$`)
-
-var nonSlugRun = regexp.MustCompile(`[^a-z0-9]+`)
-
-var diacriticFolder = strings.NewReplacer(
-	"à", "a", "á", "a", "â", "a", "ã", "a", "ä", "a", "å", "a", "ā", "a", "ă", "a", "ą", "a",
-	"æ", "ae",
-	"ç", "c", "ć", "c", "č", "c", "ĉ", "c",
-	"ď", "d", "đ", "d",
-	"è", "e", "é", "e", "ê", "e", "ë", "e", "ē", "e", "ė", "e", "ę", "e", "ě", "e",
-	"ğ", "g",
-	"ì", "i", "í", "i", "î", "i", "ï", "i", "ī", "i", "į", "i", "ı", "i",
-	"ł", "l", "ľ", "l",
-	"ñ", "n", "ń", "n", "ň", "n",
-	"ò", "o", "ó", "o", "ô", "o", "õ", "o", "ö", "o", "ø", "o", "ō", "o", "ő", "o",
-	"œ", "oe",
-	"ř", "r",
-	"ś", "s", "š", "s", "ş", "s", "ș", "s",
-	"ß", "ss",
-	"ť", "t", "ț", "t", "ţ", "t",
-	"ù", "u", "ú", "u", "û", "u", "ü", "u", "ū", "u", "ů", "u", "ű", "u", "ų", "u",
-	"ý", "y", "ÿ", "y",
-	"ź", "z", "ż", "z", "ž", "z",
-)
-
 type SocialLink struct {
 	Type string `json:"type"`
 	URL  string `json:"url"`
@@ -103,6 +77,14 @@ func (a Author) Byline() Byline {
 	return Byline{ID: a.ID, Name: a.Name, Slug: a.Slug, Bio: a.Bio, AvatarID: a.AvatarID, Website: a.Website, SocialLinks: links}
 }
 
+func BylineIDs(bylines []Byline) []uint32 {
+	ids := make([]uint32, 0, len(bylines))
+	for _, byline := range bylines {
+		ids = append(ids, byline.ID)
+	}
+	return ids
+}
+
 type Nullable[T any] struct {
 	Set   bool
 	Value *T
@@ -129,9 +111,8 @@ type Page struct {
 	Total int
 }
 
-func IsValidSlug(slug string) bool {
-	length := utf8.RuneCountInString(slug)
-	return length >= 1 && length <= MaxSlugRunes && slugPattern.MatchString(slug)
+func IsValidSlug(candidate string) bool {
+	return slug.IsValid(candidate)
 }
 
 func IsValidName(name string) bool {
@@ -191,26 +172,9 @@ func ValidateLinks(links []SocialLink) error {
 }
 
 func GenerateSlug(name string) string {
-	folded := diacriticFolder.Replace(strings.ToLower(name))
-	slug := strings.Trim(nonSlugRun.ReplaceAllString(folded, "-"), "-")
-	slug = truncateSlug(slug, MaxSlugRunes)
-	if slug == "" {
-		return FallbackSlug
-	}
-	return slug
-}
-
-func truncateSlug(slug string, limit int) string {
-	if len(slug) <= limit {
-		return slug
-	}
-	return strings.TrimRight(slug[:limit], "-")
+	return slug.Generate(name, FallbackSlug)
 }
 
 func SlugWithSuffix(base string, attempt int) string {
-	if attempt <= 1 {
-		return base
-	}
-	suffix := "-" + strconv.Itoa(attempt)
-	return truncateSlug(base, MaxSlugRunes-len(suffix)) + suffix
+	return slug.WithSuffix(base, attempt)
 }

internal/domain/author/authorRepositoryInterface.go

@@ -10,6 +10,7 @@ type Repository interface {
 	DeleteMovingCredits(id uint32, reassignTo *uint32) error
 	DeleteUncrediting(id uint32) error
 	AvatarUsage() (map[uint32]int, error)
+	FindByAvatar(imageID uint32) ([]Author, error)
 	ClearAvatar(imageID uint32) ([]uint32, error)
 	AssignAvatar(authorIDs []uint32, imageID uint32) error
 	RepointAvatar(fromImageIDs []uint32, toImageID uint32) (int, error)

internal/domain/site/siteDomain.go

@@ -18,6 +18,8 @@ var (
 	ErrInvalidLocale   = errors.New("invalid locale")
 	ErrUseSetDefault   = errors.New("the default flag is changed through the default route")
 	ErrInvalidReassign = errors.New("invalid reassign destination")
+
+	ErrInvalidTitleTemplate = errors.New("the title template must contain %title%")
 )
 
 const (
@@ -30,8 +32,14 @@ const (
 	MinNameRunes = 1
 	MaxNameRunes = 100
 
+	MaxLocaleRunes  = 35
+	MaxBaseURLRunes = 255
+
 	MinKeyRunes = 2
 	MaxKeyRunes = 32
+
+	TitlePlaceholder     = "%title%"
+	DefaultTitleTemplate = "%title% | %site%"
 )
 
 var keyPattern = regexp.MustCompile(`^[a-z0-9]+(-[a-z0-9]+)*$`)
@@ -49,6 +57,9 @@ type Site struct {
 	Locale               *string `json:"locale"`
 	IsDefault            bool    `json:"is_default"`
 	ArticleCount         int     `json:"article_count"`
+	SiteName             string  `json:"site_name"`
+	TitleTemplate        string  `json:"title_template"`
+	DefaultDescription   string  `json:"default_description"`
 }
 
 type Nullable[T any] struct {
@@ -64,6 +75,9 @@ type Patch struct {
 	Locale               Nullable[string]
 	DefaultSocialImageID Nullable[uint32]
 	IsDefault            *bool
+	SiteName             *string
+	TitleTemplate        *string
+	DefaultDescription   *string
 }
 
 func IsValidKey(key string) bool {
@@ -76,11 +90,18 @@ func IsValidName(name string) bool {
 	return length >= MinNameRunes && length <= MaxNameRunes
 }
 
+func ValidateTitleTemplate(template string) error {
+	if !strings.Contains(template, TitlePlaceholder) {
+		return ErrInvalidTitleTemplate
+	}
+	return nil
+}
+
 func NormalizeLocale(locale *string) (*string, error) {
 	if locale == nil || *locale == "" {
 		return nil, nil
 	}
-	if !localePattern.MatchString(*locale) {
+	if utf8.RuneCountInString(*locale) > MaxLocaleRunes || !localePattern.MatchString(*locale) {
 		return nil, ErrInvalidLocale
 	}
 	return locale, nil
@@ -126,7 +147,11 @@ func NormalizeBaseURL(raw string) (string, error) {
 	if found.scheme == "http" && !isLoopback(found.hostname) {
 		return "", ErrInvalidSiteURL
 	}
-	return found.scheme + "://" + found.host, nil
+	normalized := found.scheme + "://" + found.host
+	if utf8.RuneCountInString(normalized) > MaxBaseURLRunes {
+		return "", ErrInvalidSiteURL
+	}
+	return normalized, nil
 }
 
 func SeedBaseURL(publicURL string) (string, error) {

internal/domain/slug/slugDomain.go

@@ -0,0 +1,65 @@
+package slug
+
+import (
+	"regexp"
+	"strconv"
+	"strings"
+	"unicode/utf8"
+)
+
+const MaxRunes = 100
+
+var pattern = regexp.MustCompile(`^[a-z0-9]+(-[a-z0-9]+)*$`)
+
+var nonSlugRun = regexp.MustCompile(`[^a-z0-9]+`)
+
+var diacriticFolder = strings.NewReplacer(
+	"à", "a", "á", "a", "â", "a", "ã", "a", "ä", "a", "å", "a", "ā", "a", "ă", "a", "ą", "a",
+	"æ", "ae",
+	"ç", "c", "ć", "c", "č", "c", "ĉ", "c",
+	"ď", "d", "đ", "d",
+	"è", "e", "é", "e", "ê", "e", "ë", "e", "ē", "e", "ė", "e", "ę", "e", "ě", "e",
+	"ğ", "g",
+	"ì", "i", "í", "i", "î", "i", "ï", "i", "ī", "i", "į", "i", "ı", "i",
+	"ł", "l", "ľ", "l",
+	"ñ", "n", "ń", "n", "ň", "n",
+	"ò", "o", "ó", "o", "ô", "o", "õ", "o", "ö", "o", "ø", "o", "ō", "o", "ő", "o",
+	"œ", "oe",
+	"ř", "r",
+	"ś", "s", "š", "s", "ş", "s", "ș", "s",
+	"ß", "ss",
+	"ť", "t", "ț", "t", "ţ", "t",
+	"ù", "u", "ú", "u", "û", "u", "ü", "u", "ū", "u", "ů", "u", "ű", "u", "ų", "u",
+	"ý", "y", "ÿ", "y",
+	"ź", "z", "ż", "z", "ž", "z",
+)
+
+func IsValid(candidate string) bool {
+	length := utf8.RuneCountInString(candidate)
+	return length >= 1 && length <= MaxRunes && pattern.MatchString(candidate)
+}
+
+func Generate(text string, fallback string) string {
+	folded := diacriticFolder.Replace(strings.ToLower(text))
+	generated := strings.Trim(nonSlugRun.ReplaceAllString(folded, "-"), "-")
+	generated = truncate(generated, MaxRunes)
+	if generated == "" {
+		return fallback
+	}
+	return generated
+}
+
+func WithSuffix(base string, attempt int) string {
+	if attempt <= 1 {
+		return base
+	}
+	suffix := "-" + strconv.Itoa(attempt)
+	return truncate(base, MaxRunes-len(suffix)) + suffix
+}
+
+func truncate(candidate string, limit int) string {
+	if len(candidate) <= limit {
+		return candidate
+	}
+	return strings.TrimRight(candidate[:limit], "-")
+}