Initial commit: Complete CalDAV calendar synchronizer
- Rust-based CLI tool for Zoho to Nextcloud calendar sync - Selective calendar import from Zoho to single Nextcloud calendar - Timezone-aware event handling for next-week synchronization - Comprehensive configuration system with TOML support - CLI interface with debug, list, and sync operations - Complete documentation and example configurations
This commit is contained in:
Alvaro Soliverez
commit
8362ebe44b
16 changed files with 6192 additions and 0 deletions
303
README.md
Normal file
303
README.md
Normal file
|
|
@ -0,0 +1,303 @@
|
|||
# CalDAV Calendar Synchronizer
|
||||
|
||||
A Rust-based command-line tool that synchronizes calendar events between Zoho Calendar and Nextcloud via CalDAV protocol. It allows you to selectively import events from specific Zoho calendars into a single Nextcloud calendar.
|
||||
|
||||
## Features
|
||||
|
||||
- **Selective Calendar Import**: Choose which Zoho calendars to sync from
|
||||
- **Single Target Calendar**: All events consolidated into one Nextcloud calendar
|
||||
- **Timezone Support**: Handles events across different timezones correctly
|
||||
- **Next Week Focus**: Optimized for importing events for the next 7 days
|
||||
- **Simple Data Transfer**: Extracts only title, time, and duration as requested
|
||||
- **Secure Authentication**: Uses app-specific passwords for security
|
||||
- **Dry Run Mode**: Preview what would be synced before making changes
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Prerequisites
|
||||
|
||||
- Rust 1.70+ (for building from source)
|
||||
- Zoho account with CalDAV access
|
||||
- Nextcloud instance with CalDAV enabled
|
||||
- App-specific passwords for both services (recommended)
|
||||
|
||||
### 2. Installation
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone <repository-url>
|
||||
cd caldavpuller
|
||||
|
||||
# Build the project
|
||||
cargo build --release
|
||||
|
||||
# The binary will be at target/release/caldav-sync
|
||||
```
|
||||
|
||||
### 3. Configuration
|
||||
|
||||
Copy the example configuration file:
|
||||
|
||||
```bash
|
||||
cp config/example.toml config/config.toml
|
||||
```
|
||||
|
||||
Edit `config/config.toml` with your settings:
|
||||
|
||||
```toml
|
||||
# Zoho CalDAV Configuration (Source)
|
||||
[zoho]
|
||||
server_url = "https://caldav.zoho.com/caldav"
|
||||
username = "your-zoho-email@domain.com"
|
||||
password = "your-zoho-app-password"
|
||||
|
||||
# Select which calendars to import
|
||||
selected_calendars = ["Work Calendar", "Personal Calendar"]
|
||||
|
||||
# Nextcloud Configuration (Target)
|
||||
[nextcloud]
|
||||
server_url = "https://your-nextcloud-domain.com"
|
||||
username = "your-nextcloud-username"
|
||||
password = "your-nextcloud-app-password"
|
||||
target_calendar = "Imported-Zoho-Events"
|
||||
create_if_missing = true
|
||||
```
|
||||
|
||||
### 4. First Run
|
||||
|
||||
Test the configuration with a dry run:
|
||||
|
||||
```bash
|
||||
./target/release/caldav-sync --debug --list-events
|
||||
```
|
||||
|
||||
Perform a one-time sync:
|
||||
|
||||
```bash
|
||||
./target/release/caldav-sync --once
|
||||
```
|
||||
|
||||
## Configuration Details
|
||||
|
||||
### Zoho Setup
|
||||
|
||||
1. **Enable CalDAV in Zoho**:
|
||||
- Go to Zoho Mail Settings → CalDAV
|
||||
- Enable CalDAV access
|
||||
- Generate an app-specific password
|
||||
|
||||
2. **Find Calendar Names**:
|
||||
```bash
|
||||
./target/release/caldav-sync --list-events --debug
|
||||
```
|
||||
This will show all available calendars.
|
||||
|
||||
### Nextcloud Setup
|
||||
|
||||
1. **Enable CalDAV**:
|
||||
- Usually enabled by default
|
||||
- Access at `https://your-domain.com/remote.php/dav/`
|
||||
|
||||
2. **Generate App Password**:
|
||||
- Go to Settings → Security → App passwords
|
||||
- Create a new app password for the sync tool
|
||||
|
||||
3. **Target Calendar**:
|
||||
- The tool can automatically create the target calendar
|
||||
- Or create it manually in Nextcloud first
|
||||
|
||||
## Usage
|
||||
|
||||
### Command Line Options
|
||||
|
||||
```bash
|
||||
caldav-sync [OPTIONS]
|
||||
|
||||
Options:
|
||||
-c, --config <CONFIG> Configuration file path [default: config/default.toml]
|
||||
-s, --server-url <SERVER_URL> CalDAV server URL (overrides config file)
|
||||
-u, --username <USERNAME> Username for authentication (overrides config file)
|
||||
-p, --password <PASSWORD> Password for authentication (overrides config file)
|
||||
--calendar <CALENDAR> Calendar name to sync (overrides config file)
|
||||
-d, --debug Enable debug logging
|
||||
--once Perform a one-time sync and exit
|
||||
--full-resync Force a full resynchronization
|
||||
--list-events List events and exit
|
||||
-h, --help Print help
|
||||
-V, --version Print version
|
||||
```
|
||||
|
||||
### Common Operations
|
||||
|
||||
1. **List Available Events**:
|
||||
```bash
|
||||
caldav-sync --list-events
|
||||
```
|
||||
|
||||
2. **One-Time Sync**:
|
||||
```bash
|
||||
caldav-sync --once
|
||||
```
|
||||
|
||||
3. **Full Resynchronization**:
|
||||
```bash
|
||||
caldav-sync --full-resync
|
||||
```
|
||||
|
||||
4. **Override Configuration**:
|
||||
```bash
|
||||
caldav-sync --username "user@example.com" --password "app-password" --once
|
||||
```
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
### Complete Configuration Example
|
||||
|
||||
```toml
|
||||
[server]
|
||||
url = "https://caldav.zoho.com/caldav"
|
||||
username = "your-email@domain.com"
|
||||
password = "your-app-password"
|
||||
timeout = 30
|
||||
|
||||
[calendar]
|
||||
name = "Work Calendar"
|
||||
color = "#4285F4"
|
||||
|
||||
[sync]
|
||||
sync_interval = 300
|
||||
sync_on_startup = true
|
||||
weeks_ahead = 1
|
||||
dry_run = false
|
||||
|
||||
[filters]
|
||||
exclude_patterns = ["Cancelled:", "BLOCKED"]
|
||||
min_duration_minutes = 5
|
||||
max_duration_hours = 24
|
||||
|
||||
[logging]
|
||||
level = "info"
|
||||
file = "caldav-sync.log"
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
You can also use environment variables:
|
||||
|
||||
```bash
|
||||
export CALDAV_SERVER_URL="https://caldav.zoho.com/caldav"
|
||||
export CALDAV_USERNAME="your-email@domain.com"
|
||||
export CALDAV_PASSWORD="your-app-password"
|
||||
export CALDAV_CALENDAR="Work Calendar"
|
||||
|
||||
./target/release/caldav-sync
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Use App Passwords**: Never use your main account password
|
||||
2. **Secure Configuration**: Set appropriate file permissions on config files
|
||||
3. **SSL/TLS**: Always use HTTPS connections
|
||||
4. **Log Management**: Be careful with debug logs that may contain sensitive data
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Authentication Failures**:
|
||||
- Verify app-specific passwords are correctly set up
|
||||
- Check that CalDAV is enabled in both services
|
||||
- Ensure correct server URLs
|
||||
|
||||
2. **Calendar Not Found**:
|
||||
- Use `--list-events` to see available calendars
|
||||
- Check calendar name spelling
|
||||
- Verify permissions
|
||||
|
||||
3. **Timezone Issues**:
|
||||
- Events are automatically converted to UTC internally
|
||||
- Original timezone information is preserved
|
||||
- Check system timezone if times seem off
|
||||
|
||||
4. **SSL Certificate Issues**:
|
||||
- Ensure server URLs use HTTPS
|
||||
- Check if custom certificates need to be configured
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable debug logging for troubleshooting:
|
||||
|
||||
```bash
|
||||
caldav-sync --debug --list-events
|
||||
```
|
||||
|
||||
This will show detailed HTTP requests, responses, and processing steps.
|
||||
|
||||
## Development
|
||||
|
||||
### Building from Source
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone <repository-url>
|
||||
cd caldavpuller
|
||||
|
||||
# Build in debug mode
|
||||
cargo build
|
||||
|
||||
# Build in release mode
|
||||
cargo build --release
|
||||
|
||||
# Run tests
|
||||
cargo test
|
||||
|
||||
# Check code formatting
|
||||
cargo fmt --check
|
||||
|
||||
# Run linter
|
||||
cargo clippy
|
||||
```
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
caldavpuller/
|
||||
├── src/
|
||||
│ ├── main.rs # CLI interface and entry point
|
||||
│ ├── lib.rs # Library interface
|
||||
│ ├── config.rs # Configuration management
|
||||
│ ├── caldav_client.rs # CalDAV HTTP client
|
||||
│ ├── event.rs # Event data structures
|
||||
│ ├── timezone.rs # Timezone handling
|
||||
│ ├── calendar_filter.rs # Calendar filtering logic
|
||||
│ ├── sync.rs # Synchronization engine
|
||||
│ └── error.rs # Error types and handling
|
||||
├── config/
|
||||
│ ├── default.toml # Default configuration
|
||||
│ └── example.toml # Example configuration
|
||||
├── tests/
|
||||
│ └── integration_tests.rs # Integration tests
|
||||
├── Cargo.toml # Rust project configuration
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Add tests if applicable
|
||||
5. Submit a pull request
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the LICENSE file for details.
|
||||
|
||||
## Support
|
||||
|
||||
For issues and questions:
|
||||
|
||||
1. Check the troubleshooting section above
|
||||
2. Review the debug output with `--debug`
|
||||
3. Open an issue on the project repository
|
||||
4. Include your configuration (with sensitive data removed) and debug logs
|
||||
Loading…
Add table
Add a link
Reference in a new issue