caldavpuller/README.md

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

# 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:

cp config/example.toml config/config.toml

Edit config/config.toml with your settings:

# 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:

./target/release/caldav-sync --debug --list-events

Perform a one-time sync:

./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:

   ./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

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:

   caldav-sync --list-events
   

2. One-Time Sync:

   caldav-sync --once
   

3. Full Resynchronization:

   caldav-sync --full-resync
   

4. Override Configuration:

   caldav-sync --username "user@example.com" --password "app-password" --once
   

Configuration Reference

Complete Configuration Example

[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:

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:

caldav-sync --debug --list-events

This will show detailed HTTP requests, responses, and processing steps.

Development

Building from Source

# 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