Skip to content

Breaking: Update to Immich v3#654

Merged
JW-CH merged 11 commits into
mainfrom
immich_v3
Jul 2, 2026
Merged

Breaking: Update to Immich v3#654
JW-CH merged 11 commits into
mainfrom
immich_v3

Conversation

@JW-CH

@JW-CH JW-CH commented Jun 19, 2026

Copy link
Copy Markdown
Collaborator

Summary by CodeRabbit

  • New Features
    • Added a new “Asset Faces” HTTP endpoint to fetch per-asset face details for richer home-page previews.
  • Refactor
    • Standardized asset identifier handling to GUIDs across selection, filtering, and paging flows.
    • Updated album asset loading and excluded-album handling to use paginated metadata searches.
  • API / Contract Updates
    • Updated asset/media response shapes and expanded status/error responses (including structured Problem Details).
  • Bug Fixes
    • Improved handling of large album include/exclude sets via consistent pagination.
  • Tests
    • Updated unit/controller tests to match new identifiers, DTOs, and API behavior.

@coderabbitai

coderabbitai Bot commented Jun 19, 2026

Copy link
Copy Markdown

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Asset identifiers move to Guid, album asset loading switches to paginated metadata search, and the core/web API contracts add asset-face retrieval plus updated DTO shapes and response statuses. Test fixtures and assertions are updated to match the new IDs and API signatures.

Changes

Asset identity and face-data wiring

Layer / File(s) Summary
Tracker Guid contract
ImmichFrame.Core/Logic/AccountSelection/IAssetAccountTracker.cs, ImmichFrame.Core/Logic/AccountSelection/BloomFilterAssetAccountTracker.cs, ImmichFrame.Core/Logic/AccountSelection/TotalAccountImagesSelectionStrategy.cs
RecordAssetLocation and ForAsset<T> now accept Guid assetId, and the strategy forwards the Guid directly to the tracker.
Album asset search flow
ImmichFrame.Core/Helpers/AssetHelper.cs, ImmichFrame.Core/Logic/Pool/AlbumAssetsPool.cs, ImmichFrame.Core/Logic/Pool/FavoriteAssetsPool.cs, ImmichFrame.Core/Logic/Pool/PeopleAssetsPool.cs, ImmichFrame.Core/Logic/Pool/MemoryAssetsPool.cs, ImmichFrame.Core/Logic/Pool/TagAssetsPool.cs, ImmichFrame.Core/Logic/PooledImmichFrameLogic.cs
Album asset retrieval switches to paginated SearchAssetsAsync; pool logic updates ID types, totals, and Immich API call arities/arguments to match the new method shapes.
Asset face endpoint and contracts
ImmichFrame.Core/Interfaces/IImmichFrameLogic.cs, ImmichFrame.Core/Logic/MultiImmichFrameLogicDelegate.cs, ImmichFrame.WebApi/Controllers/AssetController.cs, ImmichFrame.WebApi.Tests/Controllers/AssetControllerTests.cs, immichFrame.Web/src/lib/immichFrameApi.ts, openApi/swagger.json
Asset-face retrieval is added, GetRandomImageAndInfo stops rebuilding GUIDs from IDs, and the generated client/spec update asset, face, album, and problem-details contracts plus getAsset response statuses.
Web UI face tuple and loading
immichFrame.Web/src/lib/components/elements/asset-component.svelte, immichFrame.Web/src/lib/components/elements/asset.svelte, immichFrame.Web/src/lib/components/home-page/home-page.svelte
Asset tuples gain a face-array slot, face data is fetched when needed, and rendering/indexing uses the new tuple positions and numeric duration parsing.
Pool test GUID and API updates
ImmichFrame.Core.Tests/Logic/Pool/FixtureHelpers.cs, ImmichFrame.Core.Tests/Logic/Pool/*AssetsPoolTests.cs
FixtureHelpers.GuidFor is added, and pool tests switch sample IDs, tag IDs, mocks, and assertions to GUID-based values and updated Immich API signatures.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

  • immichFrame/ImmichFrame#499: It introduced GetExcludedAlbumAssets, which this PR changes to use paginated SearchAssetsAsync instead of GetAlbumInfoAsync.
  • immichFrame/ImmichFrame#535: It touched the same excluded-album and album-loading paths now updated with SearchAssetsAsync and related test expectations.
  • immichFrame/ImmichFrame#537: It introduced tag-based asset selection code that this PR updates for GUID-based IDs and tag search inputs.

Suggested labels: enhancement

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 2.56% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check ❓ Inconclusive The title matches the Immich v3 theme, but it is too vague to convey the main code changes. Use a specific title like "Migrate asset pools and API contracts to Immich v3" so the primary change is clear.
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch immich_v3

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (1)
ImmichFrame.Core/Logic/PooledImmichFrameLogic.cs (1)

78-80: Use named arguments for ImmichApi calls with multiple null parameters.

These calls pass several positional null arguments to generated client methods with optional parameters (key, slug, isOwned, isShared, name, edited, size). Using named arguments would make the intent explicit and guard against parameter order changes during client regeneration.

Affected calls:

  • GetAssetInfoAsync(assetId, null, null)GetAssetInfoAsync(id: assetId, key: null, slug: null) (lines 78, 88)
  • GetAllAlbumsAsync(assetId, null, null, null, null)GetAllAlbumsAsync(assetId: assetId, id: null, isOwned: null, isShared: null, name: null) (line 80)
  • ViewAssetAsync(null, id, string.Empty, AssetMediaSize.Preview, null)ViewAssetAsync(edited: null, id: id, key: string.Empty, size: AssetMediaSize.Preview, slug: null) (line 143)
  • PlayAssetVideoAsync(id, null, null)PlayAssetVideoAsync(id: id, key: null, slug: null) (line 176)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@ImmichFrame.Core/Logic/PooledImmichFrameLogic.cs` around lines 78 - 80,
Replace positional null arguments with named arguments in ImmichApi method calls
to improve clarity and protect against parameter order changes. Update the
GetAssetInfoAsync call on line 78 to use named arguments for key and slug
parameters, the GetAllAlbumsAsync call on line 80 to use named arguments for id,
isOwned, isShared, and name parameters, the ViewAssetAsync call on line 143 to
use named arguments for edited, id, key, size, and slug parameters, and the
PlayAssetVideoAsync call on line 176 to use named arguments for id, key, and
slug parameters. Each call should explicitly name all parameters being passed
instead of relying on positional argument order.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ImmichFrame.Core/Helpers/AssetHelper.cs`:
- Around line 15-20: The GetExcludedAlbumAssets method in AssetHelper.cs and
LoadAssets method in AlbumAssetsPool.cs only fetch the first page of search
results, causing assets from later pages to be missed. Implement pagination in
both methods by wrapping the search call in a loop that uses Page and Size
parameters set to a batch size of 1000, accumulating results across multiple
pages until a page returns fewer items than the batch size. Follow the same
pagination pattern already implemented in FavoriteAssetsPool, PeopleAssetsPool,
and TagAssetsPool to ensure consistency across the codebase.

In `@ImmichFrame.Core/Logic/Pool/AlbumAssetsPool.cs`:
- Around line 17-19: The albumAssets query in AlbumAssetsPool is not paginated
and only retrieves the first page of results, causing large albums to have
truncated assets. Implement pagination similar to the FavoriteAssetsPool,
PeopleAssetsPool, and TagAssetsPool implementations by wrapping the
immichApi.SearchAssetsAsync call in a loop that increments the Page parameter on
MetadataSearchDto until all pages are retrieved. Apply the same pagination fix
to AssetHelper.cs where the identical issue exists.

---

Nitpick comments:
In `@ImmichFrame.Core/Logic/PooledImmichFrameLogic.cs`:
- Around line 78-80: Replace positional null arguments with named arguments in
ImmichApi method calls to improve clarity and protect against parameter order
changes. Update the GetAssetInfoAsync call on line 78 to use named arguments for
key and slug parameters, the GetAllAlbumsAsync call on line 80 to use named
arguments for id, isOwned, isShared, and name parameters, the ViewAssetAsync
call on line 143 to use named arguments for edited, id, key, size, and slug
parameters, and the PlayAssetVideoAsync call on line 176 to use named arguments
for id, key, and slug parameters. Each call should explicitly name all
parameters being passed instead of relying on positional argument order.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 021382d4-dd64-49fa-b97b-f3c51b252447

📥 Commits

Reviewing files that changed from the base of the PR and between efc850c and d437dce.

📒 Files selected for processing (24)
  • ImmichFrame.Core.Tests/Logic/Pool/AggregatingAssetPoolTests.cs
  • ImmichFrame.Core.Tests/Logic/Pool/AlbumAssetsPoolTests.cs
  • ImmichFrame.Core.Tests/Logic/Pool/AllAssetsPoolTests.cs
  • ImmichFrame.Core.Tests/Logic/Pool/CachingApiAssetsPoolTests.cs
  • ImmichFrame.Core.Tests/Logic/Pool/FavoriteAssetsPoolTests.cs
  • ImmichFrame.Core.Tests/Logic/Pool/FixtureHelpers.cs
  • ImmichFrame.Core.Tests/Logic/Pool/MemoryAssetsPoolTests.cs
  • ImmichFrame.Core.Tests/Logic/Pool/MultiAssetPoolTests.cs
  • ImmichFrame.Core.Tests/Logic/Pool/PersonAssetsPoolTests.cs
  • ImmichFrame.Core.Tests/Logic/Pool/QueuingAssetPoolTests.cs
  • ImmichFrame.Core.Tests/Logic/Pool/TagAssetsPoolTests.cs
  • ImmichFrame.Core/Helpers/AssetHelper.cs
  • ImmichFrame.Core/Logic/AccountSelection/BloomFilterAssetAccountTracker.cs
  • ImmichFrame.Core/Logic/AccountSelection/IAssetAccountTracker.cs
  • ImmichFrame.Core/Logic/AccountSelection/TotalAccountImagesSelectionStrategy.cs
  • ImmichFrame.Core/Logic/Pool/AlbumAssetsPool.cs
  • ImmichFrame.Core/Logic/Pool/FavoriteAssetsPool.cs
  • ImmichFrame.Core/Logic/Pool/MemoryAssetsPool.cs
  • ImmichFrame.Core/Logic/Pool/PeopleAssetsPool.cs
  • ImmichFrame.Core/Logic/Pool/TagAssetsPool.cs
  • ImmichFrame.Core/Logic/PooledImmichFrameLogic.cs
  • ImmichFrame.Core/OpenAPIs/immich-openapi-specs.json
  • ImmichFrame.WebApi.Tests/Controllers/AssetControllerTests.cs
  • ImmichFrame.WebApi/Controllers/AssetController.cs

Comment thread ImmichFrame.Core/Helpers/AssetHelper.cs Outdated
Comment thread ImmichFrame.Core/Logic/Pool/AlbumAssetsPool.cs Outdated

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@openApi/swagger.json`:
- Around line 537-540: The OpenAPI schema is over-restricting Guid fields by
enforcing UUIDv4 only. Update the affected schema definitions in swagger.json
for the listed DTOs (such as AssetResponseDto, AlbumResponseDto,
UserResponseDto, PersonResponseDto, TagResponseDto, AssetStackResponseDto, and
ContributorCountResponseDto) so that their uuid-format string fields no longer
use the UUIDv4-only pattern. Remove the pattern property entirely or relax it to
accept any valid Guid/UUID shape while keeping format: uuid and nullable where
applicable.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e02ff92d-96c8-4a89-95c9-532f2897c09d

📥 Commits

Reviewing files that changed from the base of the PR and between a37014c and 86c95a7.

📒 Files selected for processing (2)
  • immichFrame.Web/src/lib/immichFrameApi.ts
  • openApi/swagger.json
✅ Files skipped from review due to trivial changes (1)
  • immichFrame.Web/src/lib/immichFrameApi.ts

Comment thread openApi/swagger.json
@3rob3 3rob3 mentioned this pull request Jul 2, 2026
3 tasks

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@immichFrame.Web/src/lib/components/home-page/home-page.svelte`:
- Around line 398-407: The face-loading logic in home-page.svelte is incorrectly
gated by assetResponse.people, which can be missing when showPeopleDesc is off,
causing zoom/pan face focus to skip loading faces. Update the condition around
getAssetFaces() to rely on the zoom/pan flags directly, or ensure people is
hydrated whenever face focus is enabled, so the facesRequest path always runs
for zoom/pan assets.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 71ad4c73-2c43-474c-8d71-47b559882fb6

📥 Commits

Reviewing files that changed from the base of the PR and between 86c95a7 and accad5a.

📒 Files selected for processing (10)
  • ImmichFrame.Core/Interfaces/IImmichFrameLogic.cs
  • ImmichFrame.Core/Logic/MultiImmichFrameLogicDelegate.cs
  • ImmichFrame.Core/Logic/Pool/AlbumAssetsPool.cs
  • ImmichFrame.Core/Logic/PooledImmichFrameLogic.cs
  • ImmichFrame.WebApi/Controllers/AssetController.cs
  • immichFrame.Web/src/lib/components/elements/asset-component.svelte
  • immichFrame.Web/src/lib/components/elements/asset.svelte
  • immichFrame.Web/src/lib/components/home-page/home-page.svelte
  • immichFrame.Web/src/lib/immichFrameApi.ts
  • openApi/swagger.json
🚧 Files skipped from review as they are similar to previous changes (3)
  • ImmichFrame.Core/Logic/Pool/AlbumAssetsPool.cs
  • ImmichFrame.WebApi/Controllers/AssetController.cs
  • ImmichFrame.Core/Logic/PooledImmichFrameLogic.cs

Comment thread immichFrame.Web/src/lib/components/home-page/home-page.svelte

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
immichFrame.Web/src/lib/components/home-page/home-page.svelte (1)

398-411: 🚀 Performance & Scalability | 🟡 Minor | ⚡ Quick win

Skip face requests for video assets

asset.svelte only uses faces for the image zoom/pan overlay, and those paths are disabled for videos. Gate api.getAssetFaces(...) on !isVideoAsset(assetResponse) so video loads don’t pay for an unused request.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@immichFrame.Web/src/lib/components/home-page/home-page.svelte` around lines
398 - 411, The face lookup in the home page asset loading flow should be skipped
for video assets, since the returned faces are only used by the image zoom/pan
overlay. Update the logic around api.getAssetFaces in home-page.svelte to also
check !isVideoAsset(assetResponse) before making the request, keeping the
existing configStore zoom/pan gating intact so images still load faces when
needed.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@immichFrame.Web/src/lib/components/home-page/home-page.svelte`:
- Around line 398-411: The face lookup in the home page asset loading flow
should be skipped for video assets, since the returned faces are only used by
the image zoom/pan overlay. Update the logic around api.getAssetFaces in
home-page.svelte to also check !isVideoAsset(assetResponse) before making the
request, keeping the existing configStore zoom/pan gating intact so images still
load faces when needed.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c64235d2-5fbe-48b7-b51c-fbbd0783e0c7

📥 Commits

Reviewing files that changed from the base of the PR and between accad5a and c99ea3c.

📒 Files selected for processing (1)
  • immichFrame.Web/src/lib/components/home-page/home-page.svelte

@JW-CH JW-CH merged commit bd61632 into main Jul 2, 2026
7 checks passed
@JW-CH JW-CH changed the title Immich v3 Breaking: Update to Immich v3 Jul 2, 2026
@JW-CH JW-CH deleted the immich_v3 branch July 2, 2026 19:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant