From 8c0775e9412082ab427bb93cf40ecca6ce83c492 Mon Sep 17 00:00:00 2001
From: Shadowghost <Ghost_of_Stone@web.de>
Date: Tue, 25 Aug 2026 20:19:52 +0200
Subject: Bind the folder name an item-by-name entity resolves to

---
 MediaBrowser.Controller/Entities/BaseItem.cs | 41 ++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

(limited to 'MediaBrowser.Controller/Entities/BaseItem.cs')

diff --git a/MediaBrowser.Controller/Entities/BaseItem.cs b/MediaBrowser.Controller/Entities/BaseItem.cs
index 28f40cb7fa..d030c8f420 100644
--- a/MediaBrowser.Controller/Entities/BaseItem.cs
+++ b/MediaBrowser.Controller/Entities/BaseItem.cs
@@ -48,6 +48,10 @@ namespace MediaBrowser.Controller.Entities
 
         public const string ThemeSongFileName = "theme";
 
+        // Well below the 255 byte limit of the common Linux filesystems and the 255 character limit
+        // of Windows, so the files inside the folder still fit within MAX_PATH.
+        private const int MaxItemByNameFolderNameBytes = 128;
+
         /// <summary>
         /// The supported image extensions.
         /// </summary>
@@ -941,6 +945,43 @@ namespace MediaBrowser.Controller.Entities
             return GetSortName(Name, EnableAlphaNumericSorting, ConfigurationManager.Configuration);
         }
 
+        /// <summary>
+        /// Turns an item-by-name entity's name into a folder name every supported filesystem accepts.
+        /// </summary>
+        /// <param name="name">The entity's name.</param>
+        /// <returns>The folder name.</returns>
+        public static string GetItemByNameFolderName(string name)
+        {
+            // Trim the period at the end because windows will have a hard time with that
+            var validName = FileSystem.GetValidFilename(name).Trim().TrimEnd('.');
+
+            // Most Linux filesystems cap a path component at 255 bytes, so a name past that cannot be
+            // turned into a folder at all - and an entity with no folder can never be created, which
+            // leaves the credit behind it stuck: not refreshable, not deletable, retried on every scan.
+            // Only broken provider data gets this long, but it still has to resolve to something, so
+            // keep a readable prefix and let a hash of the whole name tell two of them apart.
+            if (Encoding.UTF8.GetByteCount(validName) <= MaxItemByNameFolderNameBytes)
+            {
+                return validName;
+            }
+
+            var suffix = "-" + validName.GetMD5().ToString("N", CultureInfo.InvariantCulture);
+            var budget = MaxItemByNameFolderNameBytes - suffix.Length;
+            var length = Math.Min(validName.Length, budget);
+            while (length > 0 && Encoding.UTF8.GetByteCount(validName.AsSpan(0, length)) > budget)
+            {
+                length--;
+            }
+
+            // Never cut a surrogate pair in half, the lone half is not a valid file name character.
+            if (length > 0 && char.IsHighSurrogate(validName[length - 1]))
+            {
+                length--;
+            }
+
+            return string.Concat(validName.AsSpan(0, length).TrimEnd().TrimEnd('.'), suffix);
+        }
+
         /// <summary>
         /// Cleans a raw name into its sortable form by applying the configured sort rules.
         /// </summary>
-- 
cgit v1.2.3