Skip to content

feat(local): add PDF thumbnails on macOS - #3017

Open
flyingrtx2333 wants to merge 1 commit into
OpenListTeam:mainfrom
flyingrtx2333:feat/local-pdf-thumbnails
Open

feat(local): add PDF thumbnails on macOS#3017
flyingrtx2333 wants to merge 1 commit into
OpenListTeam:mainfrom
flyingrtx2333:feat/local-pdf-thumbnails

Conversation

@flyingrtx2333

Copy link
Copy Markdown

Summary / 摘要

  • Add an opt-in pdf_thumbnail setting to the Local driver. It is disabled by default.
  • On macOS, render the first page of PDFs with the system Quick Look tool (/usr/bin/qlmanage).
  • Reuse the Local driver's existing signed thumbnail URLs, concurrency limiter, image resize path, and disk cache.
  • Keep PDF thumbnails unadvertised on unsupported platforms; existing image and video thumbnail behavior is unchanged.
  • Propagate request cancellation to Quick Look and enforce a 30-second render timeout.

Operational notes:

  • The existing thumbnail master switch must also be enabled.

  • Rendering invokes the macOS Quick Look process for each cache miss; configuring thumb_cache_folder is recommended.

  • Because PDF parsing consumes local resources, administrators should enable this selectively for untrusted or public storage.

  • The setting is visible on all platforms but only advertises PDF thumbnail URLs on Darwin builds.

  • This PR has breaking changes.
    / 此 PR 包含破坏性变更。

  • This PR changes public API, config, storage format, or migration behavior.
    / 此 PR 修改了公开 API、配置、存储格式或迁移行为。

  • This PR requires corresponding changes in related repositories.
    / 此 PR 需要关联仓库同步修改。

Related repository PRs / 关联仓库 PR:

  • OpenList-Frontend: Not required; driver addition fields are rendered from backend metadata.
  • OpenList-Docs: Not required for the initial implementation.

Testing / 测试

  • go test ./...
    • The Local driver passes. The full command still fails on the current clean main baseline in unrelated packages, including Go 1.27 format-string vet failures in drivers/123, drivers/189, and drivers/189pc, plus an existing nil-pointer failure in drivers/onedrive_sharelink.
  • Manual test / 手动测试:
    • GOTOOLCHAIN=local go test -race ./drivers/local — 8 tests passed.
    • GOTOOLCHAIN=local go vet ./drivers/local — passed.
    • CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go test -c ./drivers/local — produced a Linux ELF test binary.
    • CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go test -c ./drivers/local — produced a Windows PE test binary.
    • bash build.sh dev web followed by a native Darwin arm64 build — passed with the rolling frontend embedded.
    • Isolated end-to-end smoke test with a copied database and synthetic PDF: /api/fs/list returned a signed thumb; fetching it returned HTTP 200, Content-Type: image/png, valid PNG magic bytes, and one disk-cache entry.
    • The Darwin integration test creates a PDF with a Unicode/space-containing filename via cupsfilter, renders it with Quick Look, and decodes the output dimensions.

Checklist / 检查清单

  • I have read CONTRIBUTING.
    / 我已阅读 CONTRIBUTING。
  • I confirm this contribution follows the repository license, contribution policy, and code of conduct.
    / 我确认此贡献符合仓库许可证、贡献规范和行为准则。
  • I have formatted the changed code with gofmt.
    / 我已使用 gofmt 格式化变更。
  • I have requested review from relevant maintainers or code owners where applicable.
    / Draft 阶段暂未指定维护者审查。

AI Disclosure / AI 使用声明

  • This PR includes AI-assisted content.
    / 此 PR 包含 AI 辅助内容。

Tools used / 使用工具:

  • Codex

Usage scope / 使用范围:

  • Code generation / 代码生成

  • Refactoring / 重构

  • Documentation / 文档

  • Tests / 测试

  • Review assistance / 审查辅助

  • I have reviewed and validated all AI-assisted content included in this PR.
    / The human collaborator will review the draft before it is marked ready.

  • I have ensured that all AI-assisted commits include Co-Authored-By attribution.
    / AI 辅助提交包含 Co-Authored-By 归属信息。

  • I can reproduce all AI-assisted content included in this PR without any AI tools.
    / This remains for the human collaborator to confirm before marking the PR ready.

The feature request and implementation were prompted and validated by the human collaborator on a real native macOS OpenList deployment. The submitted code, tests, PR text, and pre-submission review were prepared with Codex assistance. No private deployment paths, credentials, media filenames, or screenshots are included.

- add an opt-in Local driver setting for PDF thumbnails
- render PDF first pages with macOS Quick Look
- preserve unsupported-platform behavior and cover the renderer with tests

Co-authored-by: Codex <267193182+codex@users.noreply.github.com>
@flyingrtx2333
flyingrtx2333 marked this pull request as ready for review September 1, 2026 12:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant