# WebDAV Integration for Rekordbox Reader

This document describes the WebDAV integration that allows Rekordbox Reader to work with self-hosted storage solutions like Nextcloud and ownCloud.

## 🎯 Overview

The application now supports two storage providers:
- **S3-Compatible Storage** (AWS S3, MinIO, etc.)
- **WebDAV** (Nextcloud, ownCloud, etc.)

Users can choose between these providers in the Storage Configuration page.

## 🏗️ Architecture

### Storage Provider Abstraction

The system uses a provider abstraction pattern:

```
StorageProvider Interface
├── S3Service (implements StorageProvider)
└── WebDAVService (implements StorageProvider)
```

### Key Components

1. **StorageProvider Interface** (`src/services/storageProvider.ts`)
   - Defines common operations for all storage providers
   - Factory pattern for creating providers
   - Configuration loading and validation

2. **WebDAVService** (`src/services/webdavService.ts`)
   - Implements WebDAV operations using the `webdav` npm package
   - Supports Nextcloud, ownCloud, and other WebDAV-compatible servers
   - Handles file upload, download, listing, and deletion

3. **Updated Configuration System**
   - New `/api/config/storage` endpoints
   - Support for both S3 and WebDAV configuration
   - Backward compatibility with existing S3 configuration

4. **Frontend Storage Configuration**
   - Provider selection (S3 vs WebDAV)
   - Dynamic form fields based on selected provider
   - Connection testing for both providers

## 🚀 Setup Instructions

### 1. Backend Configuration

The backend automatically detects the storage provider from the configuration file:

**File: `storage-config.json`**
```json
{
  "provider": "webdav",
  "url": "https://your-nextcloud.com/remote.php/dav/files/username/",
  "username": "your-username",
  "password": "your-password-or-app-password",
  "basePath": "/music-files"
}
```

### 2. Environment Variables

You can also configure WebDAV using environment variables:

```bash
STORAGE_PROVIDER=webdav
WEBDAV_URL=https://your-nextcloud.com/remote.php/dav/files/username/
WEBDAV_USERNAME=your-username
WEBDAV_PASSWORD=your-password-or-app-password
WEBDAV_BASE_PATH=/music-files
```

### 3. Frontend Configuration

1. Navigate to **Configuration → Storage Configuration**
2. Select **WebDAV** as the storage provider
3. Fill in your WebDAV server details:
   - **URL**: Your Nextcloud/ownCloud WebDAV URL
   - **Username**: Your account username
   - **Password**: Your password or app password
   - **Base Path**: Optional subfolder for music files
4. Click **Test Connection** to verify
5. Click **Save Configuration** to apply

## 🔧 Nextcloud Setup

### 1. Enable WebDAV

WebDAV is enabled by default in Nextcloud. You can verify this in:
- **Settings → Administration → Basic settings**

### 2. Create App Password (Recommended)

For better security, create an app password:

1. Go to **Settings → Personal → Security**
2. Scroll down to **App passwords**
3. Create a new app password for "Rekordbox Reader"
4. Use this password instead of your main password

### 3. Get WebDAV URL

Your WebDAV URL follows this pattern:
```
https://your-nextcloud.com/remote.php/dav/files/username/
```

Replace:
- `your-nextcloud.com` with your Nextcloud domain
- `username` with your Nextcloud username

### 4. Create Music Folder (Optional)

You can create a dedicated folder for music files:
1. In Nextcloud, create a folder called `music-files`
2. Set this as the `basePath` in the configuration

## 🔧 ownCloud Setup

The setup is similar to Nextcloud:

1. Enable WebDAV in ownCloud settings
2. Create an app password for security
3. Use the WebDAV URL: `https://your-owncloud.com/remote.php/dav/files/username/`
4. Configure the same way as Nextcloud

## 🧪 Testing

### Backend Test

Run the WebDAV test script:

```bash
cd packages/backend
node test-webdav.js
```

Make sure to update the configuration in the test file first.

### Frontend Test

1. Go to **Configuration → Storage Configuration**
2. Select **WebDAV** provider
3. Enter your WebDAV details
4. Click **Test Connection**
5. Verify the connection is successful

## 📁 File Operations

The WebDAV service supports all standard file operations:

- **Upload**: Upload music files to WebDAV storage
- **Download**: Download files for playback
- **List**: List all files and folders
- **Delete**: Remove files from storage
- **Metadata**: Get file information
- **Streaming**: Generate streaming URLs

## 🔒 Security Considerations

1. **Use App Passwords**: Don't use your main Nextcloud/ownCloud password
2. **HTTPS Only**: Always use HTTPS URLs for WebDAV connections
3. **Base Path**: Use a dedicated folder for music files
4. **Permissions**: Ensure the WebDAV user has appropriate permissions

## 🐛 Troubleshooting

### Common Issues

1. **Connection Failed**
   - Verify the WebDAV URL is correct
   - Check username and password
   - Ensure WebDAV is enabled on your server

2. **Permission Denied**
   - Check if the user has write permissions
   - Verify the base path exists and is accessible

3. **SSL/TLS Errors**
   - Ensure you're using HTTPS
   - Check if the SSL certificate is valid

4. **File Upload Fails**
   - Check available storage space
   - Verify file permissions
   - Ensure the file format is supported

### Debug Mode

Enable debug logging by setting:
```bash
DEBUG=webdav:*
```

## 🔄 Migration from S3

If you're migrating from S3 to WebDAV:

1. Export your current configuration
2. Set up WebDAV storage
3. Update the configuration to use WebDAV
4. The application will automatically use the new storage provider

## 📊 Performance

WebDAV performance depends on:
- Network latency to your server
- Server performance and storage type
- File sizes and concurrent operations

For best performance:
- Use a local or fast Nextcloud/ownCloud instance
- Consider using SSD storage
- Optimize your network connection

## 🎵 Supported File Formats

The WebDAV integration supports all audio formats supported by the application:
- MP3
- WAV
- FLAC
- M4A
- AAC
- OGG
- OPUS
- WMA

## 📝 API Endpoints

### Storage Configuration

- `GET /api/config/storage` - Get current storage configuration
- `POST /api/config/storage` - Save storage configuration
- `POST /api/config/storage/test` - Test storage connection

### Legacy S3 Endpoints

The following endpoints are still available for backward compatibility:
- `GET /api/config/s3` - Get S3 configuration
- `POST /api/config/s3` - Save S3 configuration
- `POST /api/config/s3/test` - Test S3 connection

## 🤝 Contributing

When adding new storage providers:

1. Implement the `StorageProvider` interface
2. Add the provider to `StorageProviderFactory`
3. Update the frontend configuration UI
4. Add appropriate tests
5. Update this documentation

## 📄 License

This WebDAV integration follows the same license as the main Rekordbox Reader project.