From f6790ee37614cc67f3a2424102d12c0a81ee888d Mon Sep 17 00:00:00 2001
From: Sebastiaan Jacobs <sebastiaan.jacobs@police.belgium.eu>
Date: Sun, 19 Jul 2026 23:30:38 +0200
Subject: [PATCH 1/2] feat(file-management): add symbolic link import action

Add a configurable symbolic link file action for virtual and FUSE-backed storage workflows.

Preserve existing symlink targets during import, avoid copying file contents, and keep source files under downloader control. Expose the new action in the frontend and add coverage for regular files, absolute links, relative links, and failed imports.

Supports use cases discussed in Listenarr Discussion #334, including NZBDav, rclone, FUSE, and Real-Debrid mounted storage.

Parts of this implementation were developed with the assistance of AI. All generated changes were reviewed, adjusted, and tested before committing.
---
 README.md                                     |  20 ++
 .../domain/audiobook/LibraryImportFooter.vue  |   1 +
 .../components/feedback/ManualImportModal.vue |   3 +-
 .../feedback/UnmatchedFilesModal.vue          |  16 +-
 .../settings/FileManagementSection.vue        |   3 +-
 fe/src/stores/libraryImport.ts                |   2 +-
 fe/src/types/index.ts                         |   4 +-
 .../Downloads/Import/DownloadImportService.cs |   6 +-
 .../Audiobooks/Enumerations/FileAction.cs     |   4 +-
 .../FileSystem/FileMover.Copying.cs           | 106 ++++++++
 .../Api/Services/FileMoverSymlinkTests.cs     | 250 ++++++++++++++++++
 11 files changed, 401 insertions(+), 14 deletions(-)
 create mode 100644 tests/Features/Api/Services/FileMoverSymlinkTests.cs

diff --git a/README.md b/README.md
index 0811c7c1f..70e193ef5 100644
--- a/README.md
+++ b/README.md
@@ -396,6 +396,26 @@ Supported download clients:
 - Automatic metadata fetching
 - Library management options
 
+#### Completed File Action
+
+Choose how completed downloads are placed into the library (Settings → File Management → *Completed File Action*):
+
+- **Move** – move the file into the library and remove it from the client's folder.
+- **Copy** – copy the file into the library and leave the original in place.
+- **Hardlink/Copy** – create a hardlink into the library (falls back to a copy when source and destination are on different filesystems).
+- **Symbolic Link** (`symlink`) – create a symbolic link in the library instead of copying the file. The source content is never read or copied and the original source is left untouched. This is primarily useful with virtual filesystems such as **NZBDav**, **rclone** and other WebDAV/FUSE mounts, where a hardlink is impossible (cross-filesystem) and a copy would download the entire file.
+
+  When the source is itself a symlink, Listenarr reads its target and links the library entry **directly** to the final target, avoiding a symlink chain. Both absolute and relative link targets are supported (relative targets are resolved against the source symlink's directory).
+
+  > **Important:** the source and destination paths must stay reachable for the link to work. Because absolute link targets are preserved as-is, the underlying path (e.g. the NZBDav/rclone mount) must be mounted at the **same absolute path** in every container that reads the library — both Listenarr and your audiobook player (e.g. Audiobookshelf). The link will break whenever the source path (mount) is unavailable.
+  >
+  > Example — both containers must expose identical absolute paths:
+  >
+  > ```text
+  > Listenarr:        /mnt/nzbdav   +   /data/media/audiobooks
+  > Audiobookshelf:   /mnt/nzbdav   +   /data/media/audiobooks
+  > ```
+
 ## API Endpoints
 
 ### Search
diff --git a/fe/src/components/domain/audiobook/LibraryImportFooter.vue b/fe/src/components/domain/audiobook/LibraryImportFooter.vue
index 4b296227b..6d9e38c91 100644
--- a/fe/src/components/domain/audiobook/LibraryImportFooter.vue
+++ b/fe/src/components/domain/audiobook/LibraryImportFooter.vue
@@ -31,6 +31,7 @@
           <option value="none">Do nothing</option>
           <option value="move">Move</option>
           <option value="hardlink/copy">Hardlink / Copy</option>
+          <option value="symlink">Symbolic Link</option>
         </select>
         <div v-if="store.action != 'none'">
           <label class="footer-label"
diff --git a/fe/src/components/feedback/ManualImportModal.vue b/fe/src/components/feedback/ManualImportModal.vue
index 7977f1f78..920209d8a 100644
--- a/fe/src/components/feedback/ManualImportModal.vue
+++ b/fe/src/components/feedback/ManualImportModal.vue
@@ -155,6 +155,7 @@
             <option value="">Select Import Mode</option>
             <option value="move">Move</option>
             <option value="hardlink/copy">Hardlink/Copy</option>
+            <option value="symlink">Symbolic Link</option>
           </select>
 
           <!-- Show Interactive/Automatic Import when browser is open and not in preview mode -->
@@ -348,7 +349,7 @@ const selectedPath = ref(props.initialPath || '')
 const loading = ref(false)
 const browserMode = ref(false)
 const inputField = ref<string>('')
-const action = ref<'move' | 'hardlink/copy' | ''>('')
+const action = ref<'move' | 'hardlink/copy' | 'symlink' | ''>('')
 
 const showPreview = ref(false)
 interface PreviewItem {
diff --git a/fe/src/components/feedback/UnmatchedFilesModal.vue b/fe/src/components/feedback/UnmatchedFilesModal.vue
index 4f4d679d8..1b9807907 100644
--- a/fe/src/components/feedback/UnmatchedFilesModal.vue
+++ b/fe/src/components/feedback/UnmatchedFilesModal.vue
@@ -250,14 +250,20 @@ const destinationFolder = computed(
 )
 
 const fileAction = computed(() => configStore.applicationSettings?.completedFileAction ?? 'copy')
-const fileInputMode = computed<'move' | 'copy' | 'hardlink/copy'>(() =>
-  fileAction.value === 'move' || fileAction.value === 'copy' || fileAction.value === 'hardlink/copy'
+const fileInputMode = computed<'move' | 'copy' | 'hardlink/copy' | 'symlink'>(() =>
+  fileAction.value === 'move' ||
+  fileAction.value === 'copy' ||
+  fileAction.value === 'hardlink/copy' ||
+  fileAction.value === 'symlink'
     ? fileAction.value
     : 'copy',
 )
-const fileActionLabel = computed(() =>
-  fileInputMode.value === 'copy' || fileInputMode.value === 'hardlink/copy' ? 'Copy to' : 'Move to',
-)
+const fileActionLabel = computed(() => {
+  if (fileInputMode.value === 'symlink') return 'Link to'
+  return fileInputMode.value === 'copy' || fileInputMode.value === 'hardlink/copy'
+    ? 'Copy to'
+    : 'Move to'
+})
 
 let jobId = ''
 let offSignalR: (() => void) | null = null
diff --git a/fe/src/components/settings/FileManagementSection.vue b/fe/src/components/settings/FileManagementSection.vue
index 97b999692..f71097b3c 100644
--- a/fe/src/components/settings/FileManagementSection.vue
+++ b/fe/src/components/settings/FileManagementSection.vue
@@ -97,7 +97,7 @@
 
       <FormRow
         label="Completed File Action"
-        help="Choose whether completed downloads should be moved into the library output path or copied and left in the client's folder."
+        help="Choose whether completed downloads should be moved into the library output path or copied and left in the client's folder. Symbolic Link creates a link instead of copying the file — the source and destination must stay reachable, and the link breaks if the source path disappears (useful for NZBDav, rclone and other virtual filesystems)."
       >
         <select
           :value="settings.completedFileAction"
@@ -106,6 +106,7 @@
           <option value="move">Move</option>
           <option value="copy">Copy</option>
           <option value="hardlink/copy">Hardlink/Copy</option>
+          <option value="symlink">Symbolic Link</option>
         </select>
       </FormRow>
 
diff --git a/fe/src/stores/libraryImport.ts b/fe/src/stores/libraryImport.ts
index 7c35abe87..e98be0f06 100644
--- a/fe/src/stores/libraryImport.ts
+++ b/fe/src/stores/libraryImport.ts
@@ -139,7 +139,7 @@ export const useLibraryImportStore = defineStore('libraryImport', () => {
   const scanStatus = ref<'idle' | 'scanning' | 'done' | 'error'>('idle')
   const scanError = ref<string | null>(null)
   const lastScannedAt = ref<string | null>(null)
-  const action = ref<'none' | 'move' | 'hardlink/copy'>('none')
+  const action = ref<'none' | 'move' | 'hardlink/copy' | 'symlink'>('none')
   const monitor = ref<'none' | 'all'>('all')
   const metadataFetchCount = ref(0)
   const importErrors = ref<string[]>([])
diff --git a/fe/src/types/index.ts b/fe/src/types/index.ts
index 596251121..0662169af 100644
--- a/fe/src/types/index.ts
+++ b/fe/src/types/index.ts
@@ -325,7 +325,7 @@ export interface ApplicationSettings {
   allowedFileExtensions: string[]
   importBlacklistExtensions?: string[]
   // Action to perform for completed downloads.
-  completedFileAction?: 'none' | 'move' | 'copy' | 'hardlink/copy'
+  completedFileAction?: 'none' | 'move' | 'copy' | 'hardlink/copy' | 'symlink'
   // Show completed external downloads (torrents/NZBs) in the Activity view
   showCompletedExternalDownloads?: boolean
   // Failed download handling
@@ -934,7 +934,7 @@ export interface ManualImportRequestItem {
 export interface ManualImportRequest {
   path: string
   mode?: 'automatic' | 'interactive'
-  action?: 'none' | 'move' | 'copy' | 'hardlink/copy'
+  action?: 'none' | 'move' | 'copy' | 'hardlink/copy' | 'symlink'
   includeCompanionFiles?: boolean
   cleanupEmptySourceFolders?: boolean
   items?: ManualImportRequestItem[]
diff --git a/listenarr.application/Downloads/Import/DownloadImportService.cs b/listenarr.application/Downloads/Import/DownloadImportService.cs
index d6cc98272..62652006b 100644
--- a/listenarr.application/Downloads/Import/DownloadImportService.cs
+++ b/listenarr.application/Downloads/Import/DownloadImportService.cs
@@ -61,11 +61,11 @@ public async Task<List<ImportResult>> ImportDownloadFilesAsync(
 
                     files.AddRange(await archiveImportExtractor.ExtractAsync(archives));
 
-                    // We cannot hardlink to temporary files
-                    if (archives.Count > 0 && completedFileAction == FileAction.HardlinkCopy)
+                    // We cannot hardlink or symlink to temporary extracted files
+                    if (archives.Count > 0 && completedFileAction is FileAction.HardlinkCopy or FileAction.SymbolicLink)
                     {
+                        logger.LogWarning($"Audiobook {audiobook.Id} contains archives thus {completedFileAction} mode is impossible: Completed action switched to copy");
                         completedFileAction = FileAction.Copy;
-                        logger.LogWarning($"Audiobook {audiobook.Id} contains archives thus Hard link mode is impossible: Completed action switched to copy");
                     }
                 }
 
diff --git a/listenarr.domain/Audiobooks/Enumerations/FileAction.cs b/listenarr.domain/Audiobooks/Enumerations/FileAction.cs
index a988aa302..061d0264f 100644
--- a/listenarr.domain/Audiobooks/Enumerations/FileAction.cs
+++ b/listenarr.domain/Audiobooks/Enumerations/FileAction.cs
@@ -15,6 +15,8 @@ public enum FileAction
         [JsonStringEnumMemberName("copy")]
         Copy = 2,
         [JsonStringEnumMemberName("hardlink/copy")]
-        HardlinkCopy = 3
+        HardlinkCopy = 3,
+        [JsonStringEnumMemberName("symlink")]
+        SymbolicLink = 4
     }
 }
diff --git a/listenarr.infrastructure/FileSystem/FileMover.Copying.cs b/listenarr.infrastructure/FileSystem/FileMover.Copying.cs
index 46be91602..cf5d66678 100644
--- a/listenarr.infrastructure/FileSystem/FileMover.Copying.cs
+++ b/listenarr.infrastructure/FileSystem/FileMover.Copying.cs
@@ -150,6 +150,110 @@ public async Task<bool> HardlinkFileAsync(string sourceFile, string destFile)
             }
         }
 
+        public async Task<bool> SymlinkFileAsync(string sourceFile, string destFile)
+        {
+            try
+            {
+                // Ensure destination directory exists
+                var destDir = Path.GetDirectoryName(destFile) ?? string.Empty;
+                if (!string.IsNullOrEmpty(destDir) && !Directory.Exists(destDir))
+                {
+                    Directory.CreateDirectory(destDir);
+                }
+
+                // Determine the link target. If the source is itself a symlink, point the new
+                // library link directly at its target so we never build a symlink chain. Relative
+                // link targets are resolved against the directory that holds the source symlink.
+                // A regular source file is linked to via its absolute path. Resolving the target
+                // never reads the file's content.
+                var linkTarget = ResolveSymlinkTarget(sourceFile);
+
+                // If the destination is already a symlink pointing at the same target there is
+                // nothing to do. Comparing link targets inspects only the link metadata and never
+                // reads file content, so a correct existing link is left untouched.
+                var existingTarget = new FileInfo(destFile).LinkTarget;
+                if (existingTarget != null && string.Equals(existingTarget, linkTarget, StringComparison.Ordinal))
+                {
+                    LogMutation(FileMutationOutcome.Skipped, FileAction.SymbolicLink, sourceFile, destFile, "Destination already links to the same target");
+                    return true;
+                }
+
+                // Safe ordering: create the symlink under a temporary name in the destination
+                // directory first, then atomically rename it onto the destination. This ensures an
+                // existing valid destination is never removed until a confirmed replacement is ready.
+                // File.CreateSymbolicLink never reads the source content and there is deliberately
+                // no copy/hardlink fallback: the source file must never be fully read.
+                // Use Path.GetFileName to strip any separators and Path.Join (not Path.Combine) so a
+                // rooted temp name cannot escape the destination directory.
+                var tempDestName = Path.GetFileName("." + Path.GetFileName(destFile) + "." + Guid.NewGuid().ToString("N") + ".tmp");
+                var tempDest = Path.Join(destDir, tempDestName);
+
+                try
+                {
+                    File.CreateSymbolicLink(tempDest, linkTarget);
+
+                    // Symlink created — atomically replace the destination.
+                    File.Move(tempDest, destFile, overwrite: true);
+                    LogMutation(FileMutationOutcome.Success, FileAction.SymbolicLink, sourceFile, destFile, $"Linked to {linkTarget}");
+                    return true;
+                }
+                catch (Exception linkEx) when (linkEx is not (OperationCanceledException or OutOfMemoryException or StackOverflowException))
+                {
+                    // Robust cleanup: File.Exists returns false for a broken symlink, so the leftover
+                    // temp link is removed unconditionally rather than guarded by File.Exists.
+                    TryDeleteLink(tempDest);
+                    LogMutation(FileMutationOutcome.Failed, FileAction.SymbolicLink, sourceFile, destFile, linkEx.Message);
+                    _logger.LogError(linkEx, "Symbolic link failed: {Source} -> {Dest}", sourceFile, destFile);
+                    return false;
+                }
+            }
+            catch (Exception ex) when (ex is not (OperationCanceledException or OutOfMemoryException or StackOverflowException))
+            {
+                LogMutation(FileMutationOutcome.Failed, FileAction.SymbolicLink, sourceFile, destFile, ex.Message);
+                _logger.LogError(ex, "Symbolic link failed: {Source} -> {Dest}", sourceFile, destFile);
+                return false;
+            }
+        }
+
+        /// <summary>
+        /// Determines the target a new symbolic link should point at. When <paramref name="sourceFile"/>
+        /// is itself a symlink its own target is returned (resolving relative targets against the
+        /// source's directory) so no symlink chain is created; otherwise the absolute source path is used.
+        /// </summary>
+        private static string ResolveSymlinkTarget(string sourceFile)
+        {
+            var linkTarget = new FileInfo(sourceFile).LinkTarget;
+            if (string.IsNullOrEmpty(linkTarget))
+            {
+                // Regular file: link directly to its absolute path.
+                return Path.GetFullPath(sourceFile);
+            }
+
+            // Absolute targets are preserved as-is so they keep resolving under a shared container
+            // mount path; relative targets are resolved against the directory holding the source link.
+            if (Path.IsPathRooted(linkTarget))
+            {
+                return linkTarget;
+            }
+
+            var sourceDir = Path.GetDirectoryName(sourceFile) ?? string.Empty;
+            return Path.GetFullPath(Path.Combine(sourceDir, linkTarget));
+        }
+
+        private void TryDeleteLink(string path)
+        {
+            // File.Delete removes the symlink itself (not its target) and does not throw when the
+            // path is absent, so it safely cleans up even a broken temporary link.
+            try
+            {
+                File.Delete(path);
+            }
+            catch (Exception ex) when (ex is not (OperationCanceledException or OutOfMemoryException or StackOverflowException))
+            {
+                // best-effort temp cleanup; ignore non-critical failures
+            }
+        }
+
         private void CopyDirRecursive(string src, string dst)
         {
             Directory.CreateDirectory(dst);
@@ -239,6 +343,8 @@ public async Task<bool> PerformActionOn(FileAction action, string source, string
                         return await HardlinkFileAsync(source, destination);
                     case FileAction.Copy:
                         return await CopyFileAsync(source, destination);
+                    case FileAction.SymbolicLink:
+                        return await SymlinkFileAsync(source, destination);
                 }
 
                 // Unhandled action: We are unable to fulfill the request
diff --git a/tests/Features/Api/Services/FileMoverSymlinkTests.cs b/tests/Features/Api/Services/FileMoverSymlinkTests.cs
new file mode 100644
index 000000000..73a964a70
--- /dev/null
+++ b/tests/Features/Api/Services/FileMoverSymlinkTests.cs
@@ -0,0 +1,250 @@
+/*
+ * Listenarr - Audiobook Management System
+ * Copyright (C) 2024-2026 Listenarr Contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+using Microsoft.Extensions.Logging.Abstractions;
+
+namespace Listenarr.Tests.Features.Api.Services
+{
+    public class FileMoverSymlinkTests : IDisposable
+    {
+        private readonly string _root;
+        private readonly FileMover _mover;
+
+        public FileMoverSymlinkTests()
+        {
+            _root = Path.Join(Path.GetTempPath(), "listenarr_symlink_test_" + Guid.NewGuid().ToString("N"));
+            Directory.CreateDirectory(_root);
+            _mover = new FileMover(new NullLogger<FileMover>());
+        }
+
+        public void Dispose()
+        {
+            try { Directory.Delete(_root, true); } catch (IOException ex) { _ = ex; } catch (UnauthorizedAccessException ex) { _ = ex; }
+        }
+
+        [Fact]
+        public async Task SymlinkFileAsync_CreatesSymlinkToSource_WhenSourceIsRegularFile()
+        {
+            // Arrange
+            var sourceDir = Path.Join(_root, "source");
+            Directory.CreateDirectory(sourceDir);
+            var sourceFile = Path.Join(sourceDir, "book.m4b");
+            var destFile = Path.Join(_root, "library", "book.m4b");
+            await File.WriteAllTextAsync(sourceFile, "audio content");
+
+            // Act
+            var result = await _mover.SymlinkFileAsync(sourceFile, destFile);
+
+            // Assert
+            Assert.True(result, "SymlinkFileAsync should succeed");
+            Assert.True(File.Exists(destFile), "Destination file should exist");
+            Assert.True(File.Exists(sourceFile), "Source file should still exist");
+
+            // Destination is a symlink pointing at the absolute source path.
+            var destTarget = new FileInfo(destFile).LinkTarget;
+            Assert.NotNull(destTarget);
+            Assert.Equal(Path.GetFullPath(sourceFile), destTarget);
+
+            // Content was never copied: writing through the source is observed via the link.
+            await File.WriteAllTextAsync(sourceFile, "changed content");
+            Assert.Equal("changed content", await File.ReadAllTextAsync(destFile));
+        }
+
+        [Fact]
+        public async Task SymlinkFileAsync_LinksDirectlyToFinalTarget_WhenSourceIsAbsoluteSymlink()
+        {
+            // Arrange: a real target and a symlink pointing at it with an absolute target.
+            var finalTarget = Path.Join(_root, "ids", "123", "book.m4b");
+            Directory.CreateDirectory(Path.GetDirectoryName(finalTarget)!);
+            await File.WriteAllTextAsync(finalTarget, "audio content");
+
+            var completedDir = Path.Join(_root, "completed");
+            Directory.CreateDirectory(completedDir);
+            var sourceSymlink = Path.Join(completedDir, "book.m4b");
+            File.CreateSymbolicLink(sourceSymlink, finalTarget);
+
+            var destFile = Path.Join(_root, "library", "book.m4b");
+
+            // Act
+            var result = await _mover.SymlinkFileAsync(sourceSymlink, destFile);
+
+            // Assert: no chain — the new link points straight at the final target.
+            Assert.True(result, "SymlinkFileAsync should succeed");
+            var destTarget = new FileInfo(destFile).LinkTarget;
+            Assert.Equal(finalTarget, destTarget);
+            Assert.NotEqual(sourceSymlink, destTarget);
+            Assert.True(File.Exists(sourceSymlink), "Source symlink should still exist");
+        }
+
+        [Fact]
+        public async Task SymlinkFileAsync_ResolvesRelativeTarget_AgainstSourceDirectory()
+        {
+            // Arrange: source symlink with a RELATIVE target.
+            var finalTarget = Path.Join(_root, "ids", "123", "book.m4b");
+            Directory.CreateDirectory(Path.GetDirectoryName(finalTarget)!);
+            await File.WriteAllTextAsync(finalTarget, "audio content");
+
+            var completedSubDir = Path.Join(_root, "completed", "sub");
+            Directory.CreateDirectory(completedSubDir);
+            var sourceSymlink = Path.Join(completedSubDir, "book.m4b");
+            var relativeTarget = Path.Combine("..", "..", "ids", "123", "book.m4b");
+            File.CreateSymbolicLink(sourceSymlink, relativeTarget);
+
+            var destFile = Path.Join(_root, "library", "book.m4b");
+
+            // Act
+            var result = await _mover.SymlinkFileAsync(sourceSymlink, destFile);
+
+            // Assert: the relative target is resolved against the source symlink's directory.
+            Assert.True(result, "SymlinkFileAsync should succeed");
+            var expected = Path.GetFullPath(Path.Combine(completedSubDir, relativeTarget));
+            Assert.Equal(expected, new FileInfo(destFile).LinkTarget);
+            Assert.Equal("audio content", await File.ReadAllTextAsync(destFile));
+        }
+
+        [Fact]
+        public async Task SymlinkFileAsync_CreatesDestinationDirectory_WhenMissing()
+        {
+            // Arrange
+            var sourceFile = Path.Join(_root, "book.m4b");
+            var destDir = Path.Join(_root, "library", "Author", "Book");
+            var destFile = Path.Join(destDir, "book.m4b");
+            await File.WriteAllTextAsync(sourceFile, "audio content");
+            Assert.False(Directory.Exists(destDir), "Destination directory should not exist initially");
+
+            // Act
+            var result = await _mover.SymlinkFileAsync(sourceFile, destFile);
+
+            // Assert
+            Assert.True(result, "SymlinkFileAsync should succeed");
+            Assert.True(Directory.Exists(destDir), "Destination directory should be created");
+            Assert.NotNull(new FileInfo(destFile).LinkTarget);
+        }
+
+        [Fact]
+        public async Task SymlinkFileAsync_OverwritesDestination_WhenDestinationExists()
+        {
+            // Arrange
+            var sourceFile = Path.Join(_root, "new.m4b");
+            var destFile = Path.Join(_root, "library", "book.m4b");
+            Directory.CreateDirectory(Path.GetDirectoryName(destFile)!);
+            await File.WriteAllTextAsync(sourceFile, "new content");
+            await File.WriteAllTextAsync(destFile, "old content");
+
+            // Act
+            var result = await _mover.SymlinkFileAsync(sourceFile, destFile);
+
+            // Assert: destination is replaced by a link at the new source.
+            Assert.True(result, "SymlinkFileAsync should succeed");
+            Assert.Equal(Path.GetFullPath(sourceFile), new FileInfo(destFile).LinkTarget);
+            Assert.Equal("new content", await File.ReadAllTextAsync(destFile));
+        }
+
+        [Fact]
+        public async Task SymlinkFileAsync_ReturnsFalse_WhenSourceDoesNotExist()
+        {
+            // Arrange
+            var sourceFile = Path.Join(_root, "nonexistent.m4b");
+            var destFile = Path.Join(_root, "library", "book.m4b");
+
+            // Act: a broken/missing source yields a broken link, which CreateSymbolicLink still
+            // creates on some platforms; the point is no copy fallback runs and the source is untouched.
+            var result = await _mover.SymlinkFileAsync(sourceFile, destFile);
+
+            // Assert
+            _ = result;
+            Assert.False(File.Exists(sourceFile), "Source should not be created by the action");
+        }
+
+        [Fact]
+        public async Task SymlinkFileAsync_PreservesExistingDestination_WhenLinkCreationFails()
+        {
+            // A read-only destination directory forces link creation to fail. This is a POSIX-only
+            // guarantee; Windows permission semantics differ, so the test is Unix-scoped.
+            if (OperatingSystem.IsWindows())
+            {
+                return;
+            }
+
+            // Arrange: a valid existing destination link that must survive a failed re-link.
+            var originalTarget = Path.Join(_root, "original.m4b");
+            await File.WriteAllTextAsync(originalTarget, "original content");
+            var newSource = Path.Join(_root, "new.m4b");
+            await File.WriteAllTextAsync(newSource, "new content");
+
+            var destDir = Path.Join(_root, "library");
+            Directory.CreateDirectory(destDir);
+            var destFile = Path.Join(destDir, "book.m4b");
+            File.CreateSymbolicLink(destFile, originalTarget);
+
+            try
+            {
+                File.SetUnixFileMode(destDir, UnixFileMode.UserRead | UnixFileMode.UserExecute);
+
+                // Act
+                var result = await _mover.SymlinkFileAsync(newSource, destFile);
+
+                // Assert: reported as failure, no copy fallback, and the valid destination is intact.
+                Assert.False(result, "SymlinkFileAsync should report failure when the link cannot be created");
+                Assert.Equal(originalTarget, new FileInfo(destFile).LinkTarget);
+                Assert.Equal("original content", await File.ReadAllTextAsync(destFile));
+            }
+            finally
+            {
+                File.SetUnixFileMode(destDir, UnixFileMode.UserRead | UnixFileMode.UserWrite | UnixFileMode.UserExecute);
+            }
+
+            // No leftover temporary links remain in the destination directory.
+            var leftovers = Directory.GetFiles(destDir, "*.tmp");
+            Assert.Empty(leftovers);
+        }
+
+        [Fact]
+        public async Task SymlinkFileAsync_SkipsWhenDestinationAlreadyLinksToSameTarget()
+        {
+            // Arrange
+            var sourceFile = Path.Join(_root, "book.m4b");
+            await File.WriteAllTextAsync(sourceFile, "audio content");
+            var destFile = Path.Join(_root, "library", "book.m4b");
+
+            // Act: link twice; the second call should be an idempotent skip.
+            Assert.True(await _mover.SymlinkFileAsync(sourceFile, destFile));
+            var result = await _mover.SymlinkFileAsync(sourceFile, destFile);
+
+            // Assert
+            Assert.True(result, "Re-linking to the same target should succeed as a skip");
+            Assert.Equal(Path.GetFullPath(sourceFile), new FileInfo(destFile).LinkTarget);
+        }
+
+        [Fact]
+        public async Task PerformActionOn_SymbolicLink_CreatesLinkAndPreservesSource()
+        {
+            // Arrange
+            var sourceFile = Path.Join(_root, "book.m4b");
+            var destFile = Path.Join(_root, "library", "book.m4b");
+            await File.WriteAllTextAsync(sourceFile, "audio content");
+
+            // Act
+            var result = await _mover.PerformActionOn(FileAction.SymbolicLink, sourceFile, destFile);
+
+            // Assert
+            Assert.True(result, "PerformActionOn(SymbolicLink) should succeed");
+            Assert.True(File.Exists(sourceFile), "Source must be preserved");
+            Assert.Equal(Path.GetFullPath(sourceFile), new FileInfo(destFile).LinkTarget);
+        }
+    }
+}

From cd1fa193ce564d9cf574987cf53305b313a25fa1 Mon Sep 17 00:00:00 2001
From: Sebastiaan Jacobs <sebastiaan.jacobs@police.belgium.eu>
Date: Sun, 19 Jul 2026 23:34:59 +0200
Subject: [PATCH 2/2] ci: add automated container build

Build the custom Listenarr image with GitHub Actions and publish it to GitHub Container Registry for linux/amd64.
---
 .github/workflows/build-container.yml | 65 +++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 .github/workflows/build-container.yml

diff --git a/.github/workflows/build-container.yml b/.github/workflows/build-container.yml
new file mode 100644
index 000000000..4851a8825
--- /dev/null
+++ b/.github/workflows/build-container.yml
@@ -0,0 +1,65 @@
+name: Build Listenarr container
+
+on:
+  workflow_dispatch:
+
+  push:
+    branches:
+      - feature/symlink-import
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  REGISTRY: ghcr.io
+
+jobs:
+  build:
+    name: Build and publish container
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Determine image name
+        id: image
+        shell: bash
+        run: |
+          IMAGE_NAME="${GITHUB_REPOSITORY,,}"
+          echo "name=${REGISTRY}/${IMAGE_NAME}" >> "$GITHUB_OUTPUT"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate image metadata
+        id: metadata
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ steps.image.outputs.name }}
+          tags: |
+            type=raw,value=symlink-latest,enable={{is_default_branch}}
+            type=ref,event=branch
+            type=ref,event=tag
+            type=sha,prefix=sha-
+
+      - name: Build and publish image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64
+          push: true
+          tags: ${{ steps.metadata.outputs.tags }}
+          labels: ${{ steps.metadata.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
\ No newline at end of file