fix(backends): copy links when the filesystem rejects symlinks (CIFS/SMB) (#10890)

[localai-bot]

Description

Fixes #10890.

Backend installation on a CIFS/SMB-backed /backends volume fails for every backend with:

failed to extract image tar: symlink libcublas.so.12.8.5.5 /backends/cuda12-llama-cpp.install-tmp/lib/libcublas.so: operation not supported

The OCI image tar is extracted via containerd's archive.Apply, which creates symlinks with os.Symlink. CIFS/SMB mounts (a common way to store /backends on a NAS) do not support symlinks and reject the syscall with operation not supported, aborting the whole install and leaving an empty backend directory. The CUDA llama.cpp image trips on the libcublas.so -> libcublas.so.12.x symlink.

Fix

When archive.Apply fails with a link-unsupported error (ENOTSUP/EOPNOTSUPP/EPERM, or the matching "operation not supported/permitted" text), the staging directory is reset and re-extracted with a pure-Go tar walker that:

• still attempts real symlinks/hardlinks first, so link semantics are preserved wherever the filesystem allows them;
• degrades an unsupported symlink/hardlink into a copy of the target file's contents in place, so the backend files remain usable;
• defers link copies to a second pass so a link appearing before its target in the tar still resolves;
• guards every entry against path traversal.

mutate.Extract already flattens the layers before this point, so the tar carries no whiteouts to interpret; a plain walker is sufficient. The primary archive.Apply path is unchanged, so this only affects filesystems that were already failing 100% of installs. The staging directory is the ephemeral, per-install *.install-tmp dir, so wiping it before the fallback pass is safe.

Tests

Added pkg/oci/extract_internal_test.go (Ginkgo/Gomega):

• isLinkUnsupportedError truth table (syscall errnos + wrapped *os.LinkError + negatives).
• safeJoin keeps entries in-root and rejects traversal.
• extractTarCopyingLinks preserves symlinks on a symlink-capable FS, and, with symlink() stubbed to return ENOTSUP, materialises the target as a real regular file copy with the right bytes.

Note

Built and verified via CI (no Go toolchain in the authoring sandbox).

Assisted-by: Claude:opus-4.8 [Claude Code]

[mudler]

@localai-bot this is not right, OCI images have layers and this as-is its not unpacking layers.

[mudler]

@localai-org-maint-bot to you to pick it up

[localai-org-maint-bot]

I picked this up and confirmed the current fallback is not safe to merge as-is. Besides bypassing OCI layer application, DownloadOCIImageTar currently appends the downloaded layers to the original image, which duplicates the layer list and reopens the source during extraction.

I prepared a replacement locally that:

• keeps mutate.Extract as the primary flattened-layer path;
• on link-unsupported targets, rewinds and applies that flattened tar with containerd archive.Apply into a link-capable staging directory, preserving whiteout/layer semantics;
• copies the staged tree to the target, resolving symlinks within the staging root only when the target filesystem rejects links;
• builds the downloaded image from empty.Image plus downloaded layers, so the original source is not reopened.

Focused fallback tests pass (6/6), all pkg/oci tests pass (15/15), go vet ./pkg/oci and golangci-lint pass, and the full e2e suite passed 94/94. I have not pushed the commit because the mandatory local pre-commit coverage ratchet failed at 40.4% versus the committed 48.5% baseline after the test suite passed; I will not bypass or weaken that gate. @mudler this PR still needs the layer-aware replacement before merge; the staged patch is preserved in the isolated worktree while the coverage-gate discrepancy is resolved.

[localai-org-maint-bot]

@mudler update: the layer-aware replacement is rebased cleanly onto current master 2b61e4b and remains staged in the isolated worktree. Fresh verification passes: the layered-image and whiteout regression, all 16 pkg/oci specs, go vet ./pkg/oci, golangci-lint with 0 issues, all 58 ./core suites, and e2e 94/94. The mandatory coverage hook is still the only blocker: all suites pass, but this host aggregates 41.2% against the current 54.2% baseline and exits nonzero; the master workflow for 2b61e4b is still queued. I have not bypassed the hook or lowered the baseline, and have not pushed an unverified commit.