Adds comprehensive documentation.
This commit is contained in:
92
docs/architecture.md
Normal file
92
docs/architecture.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# Project Architecture & Developer Setup
|
||||
|
||||
This document describes the architectural layout, internal protocols, security model, and developer setup for the **Nextcloud Upload Tool**.
|
||||
|
||||
---
|
||||
|
||||
## 1. Workspace Layout
|
||||
|
||||
The repository is organized as a Cargo workspace with three primary crates:
|
||||
|
||||
```
|
||||
nextcloud-upload-tool/
|
||||
├── nextcloud_client/ # Shared Rust core library
|
||||
│ ├── src/
|
||||
│ │ ├── auth.rs # Nextcloud Login Flow v2 client & polling
|
||||
│ │ ├── client.rs # NextcloudClient WebDAV client & status checks
|
||||
│ │ ├── config.rs # ClientConfig and URL normalization
|
||||
│ │ ├── credentials.rs # CredentialStore (OS Keychain + accounts.json)
|
||||
│ │ ├── download.rs # Direct-download URL generator
|
||||
│ │ ├── progress.rs # Async ProgressStream & progress callbacks
|
||||
│ │ └── sharing.rs # OCS Sharing API (public share link creation)
|
||||
├── cli/ # CLI binary (`nut`)
|
||||
│ └── src/
|
||||
│ └── main.rs # Clap CLI parser, upload handlers, terminal output
|
||||
├── gui/ # Desktop application (Tauri v2 + React)
|
||||
│ ├── src/ # React + TypeScript frontend
|
||||
│ │ ├── App.tsx # UI tabs, drag-and-drop, state management
|
||||
│ │ └── App.css # Styling and responsive layout
|
||||
│ └── src-tauri/ # Tauri Rust backend
|
||||
│ ├── src/commands.rs # IPC command handlers forwarding to nextcloud_client
|
||||
│ └── tauri.conf.json # Multi-platform bundle configuration
|
||||
└── docs/ # Documentation & user guides
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Shared Core Architecture (`nextcloud_client`)
|
||||
|
||||
Both the CLI and GUI frontends share the `nextcloud_client` crate to ensure consistent behavior:
|
||||
|
||||
- **WebDAV Upload Pipeline**:
|
||||
- Implements HTTP PUT requests against Nextcloud's WebDAV endpoint (`/remote.php/dav/files/<user>/<path>`).
|
||||
- Employs streaming request bodies wrapped in a custom `ProgressStream` to capture transferred byte counts in real time without buffering large files in RAM.
|
||||
- Automatically handles intermediate remote directory resolution.
|
||||
|
||||
- **OCS Sharing API**:
|
||||
- Interacts with `/ocs/v2.php/apps/files_sharing/api/v1/shares` using OCS headers (`OCS-APIRequest: true`).
|
||||
- Creates public read-only shares (`shareType=3`, `permissions=1`) with optional password protection.
|
||||
- Generates canonical public share links (`/index.php/s/<token>`) and direct download links (`/index.php/s/<token>/download`).
|
||||
|
||||
- **Unified Credential Storage**:
|
||||
- **Keyring Service**: Keyring service identifier `me.majinnaibu.nut`.
|
||||
- **Account Metadata**: Stored in `~/.config/nut/accounts.json` containing account IDs, server URLs, usernames, labels, and default account flags.
|
||||
- **Secrets**: App passwords and tokens are stored in the OS native keychain (Apple Keychain on macOS, Windows Credential Manager on Windows, and Secret Service on Linux).
|
||||
|
||||
---
|
||||
|
||||
## 3. GUI Architecture & IPC Bridge
|
||||
|
||||
The GUI is built with **Tauri v2** using a lightweight React frontend:
|
||||
- **Tauri Commands**: Defined in `gui/src-tauri/src/commands.rs` exposing async Rust functions (`upload_file`, `get_accounts`, `login_v2_start`, `login_v2_poll`, `set_default_account`, etc.) to TypeScript.
|
||||
- **Event Streaming**: As WebDAV uploads progress, the Rust backend emits `upload-progress` events to the Tauri webview containing `file_id`, `bytes_transferred`, `total_bytes`, and `percent`.
|
||||
- **Drag-and-Drop Integration**: The native OS drag-and-drop listener intercepts dropped files and invokes `get_file_info` to populate the upload queue.
|
||||
|
||||
---
|
||||
|
||||
## 4. Developer Setup & Testing
|
||||
|
||||
### Running Tests
|
||||
```bash
|
||||
# Run all unit and integration tests across the workspace
|
||||
cargo test --workspace
|
||||
|
||||
# Run CLI tests only
|
||||
cargo test -p nut
|
||||
|
||||
# Run core library tests only
|
||||
cargo test -p nextcloud_client
|
||||
```
|
||||
|
||||
### Running GUI in Development Mode
|
||||
```bash
|
||||
# In terminal 1: start Vite dev server
|
||||
cd gui
|
||||
npm install
|
||||
npm run dev
|
||||
|
||||
# In terminal 2: run Tauri dev desktop app
|
||||
cargo run -p gui
|
||||
# Or use Tauri CLI
|
||||
npm run tauri dev
|
||||
```
|
||||
51
docs/gui-guide.md
Normal file
51
docs/gui-guide.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# GUI Desktop Application Guide
|
||||
|
||||
The **Nextcloud Upload Tool GUI** is a fast desktop application designed for streamlined file queuing, drag-and-drop uploads, public share creation, and multi-account management.
|
||||
|
||||
---
|
||||
|
||||
## 1. Interface Overview
|
||||
|
||||
The interface is structured into three primary sections:
|
||||
|
||||
1. **Header Bar**:
|
||||
- Displays the application branding.
|
||||
- **Account Switcher**: Quick-switch dropdown to select the target Nextcloud account for uploads.
|
||||
- **Navigation Tabs**: Toggle between **Upload Queue** and **Accounts & Auth**.
|
||||
|
||||
2. **Upload Queue Tab**:
|
||||
- **Target Settings**: Configure remote directory on Nextcloud (default: `Uploads`), toggle public share generation, and set optional link passwords.
|
||||
- **Drag & Drop Zone**: Visual target supporting OS file drops or manual system file browser selection (`Browse Files`).
|
||||
- **Queue List**: Per-file upload queue showing status badges (`queued`, `uploading`, `completed`, `error`), live percentage, byte counters, and action buttons (`▲`, `▼`, `✕`, inline `↻ Retry`).
|
||||
- **Global Actions**: `Upload All (N)` button and `Clear Completed` / `Clear All`.
|
||||
|
||||
3. **Accounts & Auth Tab**:
|
||||
- **Connected Accounts**: Interactive cards displaying connected usernames, server endpoints, custom labels, and active default status.
|
||||
- **Browser Login (Login Flow v2)**: One-click interactive authorization opening your web browser with support for 2FA / SSO.
|
||||
- **Manual App Password Entry**: Form for connecting with custom server URLs, usernames, and generated application tokens.
|
||||
|
||||
---
|
||||
|
||||
## 2. Step-by-Step Walkthrough
|
||||
|
||||
### Connecting Your First Account
|
||||
1. Open the application and switch to the **Accounts & Auth** tab.
|
||||
2. Enter your Nextcloud server URL (e.g. `https://cloud.example.com`).
|
||||
3. Click **Authorize in Browser (Login Flow v2)**.
|
||||
4. Your default browser opens the authorization page. Click **Grant Access**.
|
||||
5. The GUI automatically polls and securely stores your token in your operating system's native keychain.
|
||||
|
||||
### Uploading Files & Creating Share Links
|
||||
1. Navigate to the **Upload Queue** tab.
|
||||
2. Drag and drop one or more files from Finder / Explorer / File Manager into the dropzone.
|
||||
3. (Optional) Check **Generate public share link** and specify a **Share password** if needed.
|
||||
4. Set the **Remote Directory** (e.g. `Projects/Assets` or `Uploads`).
|
||||
5. Click **Upload All**.
|
||||
6. Real-time progress bars update for both the total batch and each individual file.
|
||||
7. Once finished:
|
||||
- Click **Copy Link** to copy the public share URL to clipboard.
|
||||
- Click **Copy Direct Download** to copy the raw download URL.
|
||||
|
||||
### Managing Failed Uploads
|
||||
- If any file fails (e.g. due to network glitch or server quota), an error badge is displayed with details.
|
||||
- Click the inline **↻ Retry** button next to that item to re-attempt the upload immediately without resetting the queue.
|
||||
77
docs/installation.md
Normal file
77
docs/installation.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# Installation Guide
|
||||
|
||||
**Nextcloud Upload Tool (`nut`)** is available as a standalone command-line tool and a desktop GUI application across macOS, Windows, and Linux.
|
||||
|
||||
---
|
||||
|
||||
## 1. Pre-built Binaries & Installers
|
||||
|
||||
Download pre-built releases for your operating system from the [Releases](https://github.com/majinnaibu/nextcloud-upload-tool/releases) page.
|
||||
|
||||
### macOS (Apple Silicon & Intel)
|
||||
- **GUI Desktop App**: Download the `.dmg` installer, open it, and drag `Nextcloud Upload Tool.app` into `/Applications`.
|
||||
- **CLI Binary**:
|
||||
```bash
|
||||
# Apple Silicon (M1/M2/M3/M4)
|
||||
curl -fsSL https://github.com/majinnaibu/nextcloud-upload-tool/releases/latest/download/nut-aarch64-apple-darwin.tar.gz | tar -xz
|
||||
sudo mv nut /usr/local/bin/
|
||||
|
||||
# Intel x86_64
|
||||
curl -fsSL https://github.com/majinnaibu/nextcloud-upload-tool/releases/latest/download/nut-x86_64-apple-darwin.tar.gz | tar -xz
|
||||
sudo mv nut /usr/local/bin/
|
||||
```
|
||||
|
||||
### Linux (Debian, Ubuntu, Fedora, Arch, Generic)
|
||||
- **Debian / Ubuntu (`.deb`)**:
|
||||
```bash
|
||||
sudo dpkg -i nextcloud-upload-tool_0.1.0_amd64.deb
|
||||
sudo apt-get install -f
|
||||
```
|
||||
- **Fedora / RHEL (`.rpm`)**:
|
||||
```bash
|
||||
sudo rpm -i nextcloud-upload-tool-0.1.0-1.x86_64.rpm
|
||||
```
|
||||
- **Universal AppImage**:
|
||||
```bash
|
||||
chmod +x Nextcloud_Upload_Tool_0.1.0_amd64.AppImage
|
||||
./Nextcloud_Upload_Tool_0.1.0_amd64.AppImage
|
||||
```
|
||||
- **Static CLI Binary (musl libc - zero external dependencies)**:
|
||||
```bash
|
||||
curl -fsSL https://github.com/majinnaibu/nextcloud-upload-tool/releases/latest/download/nut-x86_64-unknown-linux-musl.tar.gz | tar -xz
|
||||
sudo mv nut /usr/local/bin/
|
||||
```
|
||||
|
||||
### Windows
|
||||
- **GUI Installer (`.msi` / NSIS `.exe`)**: Download and run `Nextcloud-Upload-Tool-Setup.exe` or `Nextcloud-Upload-Tool.msi`. Follow the installer wizard.
|
||||
- **Standalone CLI**: Download `nut-x86_64-pc-windows-msvc.zip`, extract `nut.exe`, and add it to your system `%PATH%`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Building from Source
|
||||
|
||||
### Prerequisites
|
||||
- **Rust toolchain** (1.75+): Install via `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
|
||||
- **Node.js** (v20+) and **npm** (for GUI frontend build)
|
||||
- **Platform Development Libraries**:
|
||||
- **Linux**: `sudo apt-get install libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev libssl-dev patchelf`
|
||||
- **macOS**: Xcode Command Line Tools (`xcode-select --install`)
|
||||
- **Windows**: Visual Studio C++ Build Tools
|
||||
|
||||
### Build the CLI (`nut`)
|
||||
```bash
|
||||
git clone https://github.com/majinnaibu/nextcloud-upload-tool.git
|
||||
cd nextcloud-upload-tool
|
||||
|
||||
cargo build --release -p nut
|
||||
# The binary is placed at target/release/nut
|
||||
```
|
||||
|
||||
### Build the Desktop GUI
|
||||
```bash
|
||||
cd gui
|
||||
npm install
|
||||
npm run build
|
||||
npm run tauri build
|
||||
# The packaged bundle is located in gui/src-tauri/target/release/bundle/
|
||||
```
|
||||
92
docs/multi-account.md
Normal file
92
docs/multi-account.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# Multi-Account Management Guide
|
||||
|
||||
**Nextcloud Upload Tool** supports managing multiple Nextcloud instances and user accounts simultaneously. Credentials, account metadata, and active default states are shared seamlessly between the CLI and GUI frontends.
|
||||
|
||||
---
|
||||
|
||||
## 1. How Accounts Are Identified
|
||||
|
||||
Every configured account has a canonical ID in the format:
|
||||
```
|
||||
username@host
|
||||
```
|
||||
*(e.g. `alice@cloud.example.com` or `dev@nextcloud.local`)*
|
||||
|
||||
You can also assign an optional friendly **label** (e.g. `"Work"`, `"Personal"`, `"Backup"`).
|
||||
|
||||
---
|
||||
|
||||
## 2. Managing Accounts via CLI (`nut`)
|
||||
|
||||
### Listing Configured Accounts
|
||||
```bash
|
||||
nut accounts
|
||||
# or
|
||||
nut account list
|
||||
```
|
||||
Outputs:
|
||||
```text
|
||||
Configured Nextcloud Accounts:
|
||||
|
||||
• alice@cloud.example.com * (active default)
|
||||
Username: alice
|
||||
Server: https://cloud.example.com
|
||||
Label: Work
|
||||
|
||||
• bob@nextcloud.org
|
||||
Username: bob
|
||||
Server: https://nextcloud.org
|
||||
Label: Personal
|
||||
```
|
||||
|
||||
To output as JSON or TSV for scripting:
|
||||
```bash
|
||||
nut accounts --json
|
||||
nut accounts --tsv
|
||||
```
|
||||
|
||||
### Adding an Account
|
||||
- **Interactive Browser Flow**:
|
||||
```bash
|
||||
nut login https://cloud.example.com --label "Work"
|
||||
```
|
||||
- **Interactive Terminal Password Prompt**:
|
||||
```bash
|
||||
nut login https://cloud.example.com --manual --label "Work"
|
||||
```
|
||||
- **Non-Interactive / Headless / Scripting**:
|
||||
```bash
|
||||
nut login https://cloud.example.com -u alice -p "app-password-token" --label "Work"
|
||||
```
|
||||
|
||||
### Switching the Active Default Account
|
||||
```bash
|
||||
# Set default by label
|
||||
nut account default Work
|
||||
|
||||
# Or set default by full account ID
|
||||
nut account default alice@cloud.example.com
|
||||
```
|
||||
|
||||
### Uploading to a Specific Account
|
||||
Use the `--account` / `-a` flag on any upload command to override the active default for that invocation:
|
||||
```bash
|
||||
nut upload --account "Work" report.pdf
|
||||
nut upload --account "bob@nextcloud.org" archive.zip
|
||||
```
|
||||
|
||||
### Removing an Account
|
||||
```bash
|
||||
nut account delete "Work"
|
||||
```
|
||||
This removes the account from `~/.config/nut/accounts.json` and deletes the associated app token from your OS keychain.
|
||||
|
||||
---
|
||||
|
||||
## 3. Managing Accounts in the GUI
|
||||
|
||||
1. Open the **Accounts & Auth** tab.
|
||||
2. The list of connected accounts displays each account's server URL, username, label, and whether it is marked as default.
|
||||
3. Click **Set as Default** on any account card to switch the primary default.
|
||||
4. Click **Select as Active** to switch the current session's upload destination.
|
||||
5. Click **Logout / Remove** to purge credentials from the OS keychain.
|
||||
Reference in New Issue
Block a user