Skip to content

v2.7.md

Latest commit

 

History

History
220 lines (153 loc) · 9.09 KB

v2.7.md

File metadata and controls

220 lines (153 loc) · 9.09 KB

v2.7 — WebDAV, Download Integrations & Archive Processing

Ship WebDAV access and server-side file-processing workflows without turning basic personal tasks into Pro-only features.

v2.6 already pulled forward the first operator features: audit log and site announcements. v2.7 therefore moves to the file workflow layer: WebDAV protocol access, archive compression/extraction for small files, plus remote-download orchestration through user-owned download engines.

Product Boundary

The rule is simple:

  • Community gets WebDAV protocol access, bounded small-file archive processing, and remote-download integrations with user-configured download engines.
  • Pro is not required for remote download. ZPan Cloud must not run a downloader execution service in v2.7.

This keeps normal file utility features free while avoiding unstable Worker behavior for long-running downloads. ZPan remains the control plane; Aria2, qBittorrent, and future download engines perform the actual transfer work.

Major Features

WebDAV Protocol Access

Add a standards-based WebDAV endpoint so users can mount ZPan from native file managers and sync tools.

Supported methods in v2.7:

  • OPTIONS
  • PROPFIND
  • GET
  • HEAD
  • PUT
  • DELETE
  • MKCOL
  • MOVE
  • COPY

Authentication:

  • Use dedicated API keys or app passwords, not browser session cookies
  • Scope credentials to a user and optionally to an organization
  • Reuse the existing permission model for file access
  • Never expose storage credentials to WebDAV clients

Path model:

  • Mount root exposes the user's accessible workspaces
  • Workspace roots map to existing org file trees
  • WebDAV paths resolve to matters records, not raw object keys
  • Object storage remains an implementation detail behind ZPan

Upload and write behavior:

  • PUT writes through ZPan's normal storage abstraction
  • MOVE and COPY reuse existing file operations
  • Conflict handling follows WebDAV semantics where possible
  • Directory creation maps to folder matters

This is a Community feature. WebDAV is a compatibility protocol for using ZPan's existing file system from external clients, not an operator-only capability.

Archive Jobs

Add a local job model for compression and extraction.

  • Job types: compress, extract
  • Statuses: queued, running, completed, failed, canceled
  • Progress fields: input bytes, output bytes, processed bytes, file count, current filename
  • Targets: current folder by default, explicit target folder optional
  • Execution: async job queue; API requests create jobs and return immediately
  • UI: file action menu, batch toolbar, job drawer, retry failed job where safe

Archive jobs are a shared foundation for Community execution now and possible larger processing execution later.

Community Small Archive Processing

Small zip workflows are included in Community.

Supported in v2.7:

  • Compress selected files/folders into .zip
  • Extract .zip into the current or selected folder
  • Preserve directory structure
  • Write results directly back to the configured object storage
  • Create normal matters records for generated files

Default local limits:

  • Total compression input: 50 MB
  • Total extraction output: 100 MB
  • Single file: 25 MB
  • File count: 200
  • Directory depth: 10

The limits are intentionally conservative for Cloudflare Workers and small self-hosted deployments. They can be raised later only after runtime verification.

Safe Extract Validation

Extraction must inspect the archive before writing output.

Validation rules:

  • Reject paths containing ..
  • Reject absolute paths
  • Reject empty names
  • Reject entries that exceed max depth
  • Reject archives whose declared uncompressed size exceeds the limit
  • Reject archives whose file count exceeds the limit
  • Reject unsupported entry types

Zip extraction must fail before writing any output if validation fails. Partial success is not a valid user-visible result.

Remote Download Integrations

Remote download is a Community feature because the execution happens on infrastructure the instance owner configures and controls.

Supported engines in v2.7:

  • Aria2 — HTTP/HTTPS, FTP, magnet, and BitTorrent tasks through JSON-RPC
  • qBittorrent — torrent and magnet tasks through the Web API
  • ZPan net-disk downloader adapter — interface reserved for a future first-party downloader that can handle selected net-disk providers

ZPan owns task creation, target folder selection, progress display, file import, quota checks, and final matters records. Download engines own fetching bytes, retrying source transfers, and keeping temporary files until ZPan imports them.

Flow:

  1. User creates a remote download job in ZPan
  2. ZPan selects a configured download engine for the requested source type
  3. ZPan submits the task to Aria2, qBittorrent, or a compatible future adapter
  4. ZPan polls or receives progress from the engine
  5. When the engine finishes, ZPan imports the completed file into the selected storage and folder
  6. ZPan creates the final file record and clears the engine-side temporary task according to the configured cleanup policy

Engine configuration:

  • Admins configure engine endpoint, credentials, default save path, and concurrency limits
  • Credentials are stored as instance secrets and are never exposed to browser clients
  • Engine health is visible in the admin settings page
  • Users can only create jobs against engines enabled by the admin

The first implementation should define a small internal downloader interface instead of baking Aria2 or qBittorrent details into route handlers. The interface should be narrow: create task, read task status, cancel task, and resolve completed output files.

Large Processing Escalation

When a Community archive job exceeds local limits, ZPan should fail clearly. A later processing service may handle large archive/media/document work, but v2.7 does not introduce Cloud downloader execution.

Future processing service candidates:

  • Large zip compression
  • Large zip extraction
  • tar, tar.gz, 7z, and rar
  • Password-protected archives
  • Future thumbnail, media probing, transcoding, and document conversion

Remote download stays outside this Pro processing bucket unless the product direction changes explicitly.

Security and Abuse Controls

WebDAV:

  • Require app-password/API-key authentication
  • Rate-limit write-heavy methods
  • Normalize and validate every path segment before lookup
  • Reject path traversal and ambiguous encoded paths
  • Keep storage object keys hidden from clients
  • Apply the same quota checks as browser uploads

Archive processing:

  • Enforce max input bytes before compression
  • Enforce declared max output bytes before extraction
  • Validate paths before writing any object
  • Avoid overwriting existing files unless the user selected a conflict strategy
  • Record job failure with a specific error message

Remote download:

  • Block private IP ranges, localhost, link-local, and metadata endpoints
  • Restrict redirects through the same SSRF checks
  • Apply per-engine and per-instance concurrency limits
  • Apply local monthly bytes and job-count quotas
  • Do not store source credentials longer than the job requires
  • Keep source URL, output size, and failure reason in the job audit trail
  • Keep download-engine credentials server-side only

Non-goals for v2.7

  • Full WebDAV locking support
  • CalDAV/CardDAV
  • WebDAV search extensions
  • Exposing raw S3 object keys over WebDAV
  • Full net-disk provider coverage
  • Browser-side zip generation for server files
  • Silent best-effort extraction after partial failures
  • Large archive handling in plain Workers
  • ZPan Cloud downloader execution
  • yt-dlp hosted by ZPan Cloud
  • Full media transcoding
  • Public plugin API for third-party processors

User Scenarios

Desktop file manager user:

I add my ZPan WebDAV URL to Finder, Windows Explorer, or a sync client, authenticate with an app password, and browse my ZPan files like a mounted drive.

Self-hosted personal user:

I select a small folder of documents, click Compress, and ZPan creates documents.zip in the same folder without requiring Pro.

User receiving a small archive:

I upload a small zip, click Extract here, and ZPan expands it into normal files after validating the archive.

Self-hosted user using remote download:

I configure my Aria2 RPC endpoint in Admin settings, paste a direct URL or magnet link in ZPan, and the completed file is imported into my selected ZPan folder.

Torrent user using qBittorrent:

I connect ZPan to my existing qBittorrent instance, add a magnet task from the web UI, and ZPan tracks progress until the finished content is imported into object storage.

Large archive user:

I try to extract a 4 GB zip on a Cloudflare Workers deployment. ZPan refuses the local job and explains that large archive processing is outside the local runtime limits.

v1 Issues Resolved

  • WebDAV protocol access — shipped as Community external-client compatibility
  • Remote URL download — shipped as Community orchestration through Aria2, qBittorrent, and future compatible download adapters
  • Archive compression/extraction — shipped as bounded Community file processing