Skip to content

Add WiFi deck download support with server manifest - #26

Open
jmahmood wants to merge 1 commit into
masterfrom
claude/download-decks-server-url-20y5v4
Open

jmahmood wants to merge 1 commit into
masterfrom
claude/download-decks-server-url-20y5v4

Conversation

@jmahmood

@jmahmood jmahmood commented Jul 8, 2026

Copy link
Copy Markdown
Owner

Summary

Add optional WiFi-based deck downloading for the parent-mode appliance, allowing decks to be hosted on any plain HTTP(S) server and downloaded directly into the import folder without requiring SD card access or SSH.

Key Changes

  • New deck_download.py module: Implements secure, hardened deck downloading with:

    • Support for both direct .apkg URLs and JSON deck manifests
    • Streamed downloads to .part files with byte-cap enforcement (1 GiB default)
    • Zip archive validation before atomic rename to prevent corrupt files from dropped connections or captive portals
    • Scheme-restricted urllib opener (http/https only, even across redirects)
    • Safe filename sanitization to prevent directory traversal attacks
    • Standard library only (urllib, json, zipfile)
  • Parent-mode UI: New "Download decks (WiFi)" screen in app.py:

    • Fetches and displays available decks from configured server
    • Shows deck names and sizes with live download progress
    • Automatically imports downloaded decks
    • Graceful error handling for network failures
  • CLI support: New python main.py download command:

    • Fetch-only mode (no import) into data/import/
    • --list flag to preview available decks
    • --deck NAME to selectively download specific decks
    • Uses deck_server_url setting as default
  • Import enhancement: python main.py import now accepts http(s) URLs in addition to file paths

  • Configuration: New deck_server_url setting in settings.json for the server endpoint (either direct .apkg or JSON manifest URL)

  • Documentation: Updated README with deck download workflow, manifest format, and security model

Implementation Details

  • Manifest format supports both {"decks": [...]} and bare list syntax
  • Relative URLs in manifests are resolved against the manifest's own URL
  • Downloads include Content-Length header parsing for progress reporting
  • Connection loss detection via early-close and byte-count mismatch
  • Filenames derived from manifest name field or URL path, with hostile characters neutralized
  • Progress callback throttled to ~100ms intervals to avoid excessive UI redraws
  • All network errors converted to user-friendly DownloadError exceptions

https://claude.ai/code/session_01JUC6t25ShAwWjEeKK1fvvt

Getting an .apkg onto the handheld previously meant pulling the SD
card or SSH. Now a parent can host decks on any plain HTTP(S) server
(python -m http.server, a NAS, nginx, a static bucket) and the device
fetches them over WiFi — using only the standard library (urllib +
json + zipfile), per the project's no-new-dependencies policy.

- cardbrick/deck_download.py: fetch_deck_list() reads either a direct
  .apkg URL or a JSON deck list ({"decks": [{"name", "url"|"file",
  "size"}]}, relative URLs resolved against the manifest);
  download_deck() streams to a .part file with a 1 GiB cap, verifies
  the result is a real zip, then renames atomically, so a dropped
  connection or captive-portal page never leaves a corrupt .apkg.
  Only http/https are followed, redirects included (the default urllib
  opener would follow a redirect to file://), and manifest filenames
  are reduced to a safe basename.
- Parent mode gains a "Download decks (WiFi)" screen: lists the
  server's decks with sizes, downloads with a progress readout into
  the existing import/ folder, and imports immediately. The server URL
  is a new deck_server_url key in settings.json — set once by editing
  the file on the SD card, consistent with settings being
  hand-editable on purpose (no on-device URL keyboard).
- CLI: `main.py import <url>` downloads then imports;
  `main.py download [url] [--list] [--deck NAME]` fetches into
  import/ without importing (URL defaults to the setting).
- Tests run against a real local http.server: manifest parsing,
  relative/hostile entries, non-zip rejection, size cap, 404s, scheme
  restrictions, filename sanitisation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JUC6t25ShAwWjEeKK1fvvt
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.

2 participants