adding card dav and cald dav
This commit is contained in:
DioCrafts
@@ -0,0 +1,262 @@
|
||||
# CardDAV Implementation Plan
|
||||
|
||||
## Introduction
|
||||
|
||||
This document outlines the plan for implementing CardDAV support in OxiCloud. CardDAV is an open protocol for synchronizing address books/contacts between different applications and devices.
|
||||
|
||||
## Implementation Roadmap
|
||||
|
||||
The implementation will follow these steps:
|
||||
|
||||
### Phase 1: Core Infrastructure (Week 1)
|
||||
|
||||
#### Database Schema
|
||||
- Create new migration for CardDAV tables:
|
||||
- `address_books` - For storing address book collections
|
||||
- `contacts` - For storing contact information
|
||||
- `address_book_shares` - For sharing address books between users
|
||||
- `contact_groups` - For organizing contacts into groups
|
||||
- `group_memberships` - For associating contacts with groups
|
||||
|
||||
#### Domain Layer
|
||||
- Define entity models:
|
||||
- `Contact` - Core contact entity
|
||||
- `AddressBook` - Collection entity
|
||||
- `ContactGroup` - For grouping contacts
|
||||
- Create repository interfaces:
|
||||
- `ContactRepository` - For contact CRUD operations
|
||||
- `AddressBookRepository` - For address book management
|
||||
- `ContactGroupRepository` - For group management
|
||||
|
||||
#### Testing
|
||||
- Unit tests for entity models
|
||||
- Repository interface contract tests
|
||||
|
||||
### Phase 2: Infrastructure Layer (Week 2)
|
||||
|
||||
#### Repository Implementations
|
||||
- Implement PostgreSQL repositories:
|
||||
- `ContactPgRepository`
|
||||
- `AddressBookPgRepository`
|
||||
- `ContactGroupPgRepository`
|
||||
- Implement vCard parsing and generation utilities
|
||||
- Create data migration tools (if needed)
|
||||
|
||||
#### Integration
|
||||
- Update dependency injection system to include new repositories
|
||||
- Connect with existing auth system
|
||||
|
||||
#### Testing
|
||||
- Repository implementation tests
|
||||
- vCard parsing/generation tests
|
||||
- Integration tests with database
|
||||
|
||||
### Phase 3: Application Layer (Week 3)
|
||||
|
||||
#### Services
|
||||
- Implement business logic services:
|
||||
- `ContactService` - Contact management
|
||||
- `AddressBookService` - Address book management
|
||||
- `ContactGroupService` - Group management
|
||||
|
||||
#### DTOs and Ports
|
||||
- Create DTOs for contact operations
|
||||
- Define service interface ports
|
||||
- Implement request/response mapping
|
||||
|
||||
#### CardDAV Adapter
|
||||
- Create adapter for CardDAV protocol translation
|
||||
- Implement vCard conversion logic
|
||||
- Create XML parsing and generation utilities
|
||||
|
||||
#### Testing
|
||||
- Service unit tests
|
||||
- Integration tests for adapter
|
||||
|
||||
### Phase 4: Interface Layer (Week 4)
|
||||
|
||||
#### REST API
|
||||
- Create REST endpoints for address book operations
|
||||
- Implement contact management endpoints
|
||||
- Add contact group endpoints
|
||||
- Document API with OpenAPI
|
||||
|
||||
#### CardDAV Protocol Endpoints
|
||||
- Implement WebDAV method handlers:
|
||||
- PROPFIND - For discovery and property retrieval
|
||||
- REPORT - For querying contacts
|
||||
- MKCOL - For creating address books
|
||||
- GET/PUT/DELETE - For contact operations
|
||||
- Add CardDAV-specific XML handling
|
||||
|
||||
#### Integration
|
||||
- Connect all layers
|
||||
- Perform end-to-end testing
|
||||
- Test with various CardDAV clients
|
||||
|
||||
#### Testing
|
||||
- API endpoint tests
|
||||
- CardDAV protocol compliance tests
|
||||
- Client compatibility tests
|
||||
|
||||
### Phase 5: Refinement and Optimization (Week 5)
|
||||
|
||||
#### Performance Optimization
|
||||
- Add caching for frequently accessed resources
|
||||
- Optimize database queries
|
||||
- Implement efficient synchronization mechanisms
|
||||
|
||||
#### Security Hardening
|
||||
- Review authentication and authorization
|
||||
- Validate input and output
|
||||
- Add rate limiting
|
||||
|
||||
#### Final Testing
|
||||
- Stress testing with large address books
|
||||
- Security testing
|
||||
- User acceptance testing
|
||||
|
||||
#### Documentation
|
||||
- Update API documentation
|
||||
- Create user guides
|
||||
- Document client setup procedures
|
||||
|
||||
## Technical Specifications
|
||||
|
||||
### Database Schema
|
||||
|
||||
```sql
|
||||
-- Address books table
|
||||
CREATE TABLE IF NOT EXISTS carddav.address_books (
|
||||
id UUID PRIMARY KEY,
|
||||
name VARCHAR(255) NOT NULL,
|
||||
owner_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
|
||||
description TEXT,
|
||||
color VARCHAR(50),
|
||||
is_public BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE(owner_id, name)
|
||||
);
|
||||
|
||||
-- Address book sharing
|
||||
CREATE TABLE IF NOT EXISTS carddav.address_book_shares (
|
||||
address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
|
||||
user_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
|
||||
can_write BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
PRIMARY KEY(address_book_id, user_id)
|
||||
);
|
||||
|
||||
-- Contacts table
|
||||
CREATE TABLE IF NOT EXISTS carddav.contacts (
|
||||
id UUID PRIMARY KEY,
|
||||
address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
|
||||
uid VARCHAR(255) NOT NULL,
|
||||
full_name VARCHAR(255),
|
||||
first_name VARCHAR(255),
|
||||
last_name VARCHAR(255),
|
||||
nickname VARCHAR(255),
|
||||
email JSONB,
|
||||
phone JSONB,
|
||||
address JSONB,
|
||||
organization VARCHAR(255),
|
||||
title VARCHAR(255),
|
||||
notes TEXT,
|
||||
photo_url TEXT,
|
||||
birthday DATE,
|
||||
anniversary DATE,
|
||||
vcard TEXT NOT NULL,
|
||||
etag VARCHAR(255) NOT NULL,
|
||||
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE(address_book_id, uid)
|
||||
);
|
||||
|
||||
-- Contact groups
|
||||
CREATE TABLE IF NOT EXISTS carddav.contact_groups (
|
||||
id UUID PRIMARY KEY,
|
||||
address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
|
||||
name VARCHAR(255) NOT NULL,
|
||||
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
|
||||
-- Group memberships
|
||||
CREATE TABLE IF NOT EXISTS carddav.group_memberships (
|
||||
group_id UUID NOT NULL REFERENCES carddav.contact_groups(id) ON DELETE CASCADE,
|
||||
contact_id UUID NOT NULL REFERENCES carddav.contacts(id) ON DELETE CASCADE,
|
||||
PRIMARY KEY(group_id, contact_id)
|
||||
);
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
#### REST API
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/address-books` | List all address books |
|
||||
| POST | `/api/address-books` | Create a new address book |
|
||||
| GET | `/api/address-books/:id` | Get a specific address book |
|
||||
| PUT | `/api/address-books/:id` | Update an address book |
|
||||
| DELETE | `/api/address-books/:id` | Delete an address book |
|
||||
| GET | `/api/address-books/:id/contacts` | List contacts in an address book |
|
||||
| POST | `/api/address-books/:id/contacts` | Create a new contact |
|
||||
| GET | `/api/address-books/:id/contacts/:contactId` | Get a specific contact |
|
||||
| PUT | `/api/address-books/:id/contacts/:contactId` | Update a contact |
|
||||
| DELETE | `/api/address-books/:id/contacts/:contactId` | Delete a contact |
|
||||
|
||||
#### CardDAV Protocol Endpoints
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| PROPFIND | `/carddav/` | List all address books |
|
||||
| PROPFIND | `/carddav/:addressBookId/` | Get address book information |
|
||||
| REPORT | `/carddav/:addressBookId/` | Query contacts in an address book |
|
||||
| GET | `/carddav/:addressBookId/:contactId.vcf` | Get a specific contact (vCard) |
|
||||
| PUT | `/carddav/:addressBookId/:contactId.vcf` | Create or update a contact |
|
||||
| DELETE | `/carddav/:addressBookId/:contactId.vcf` | Delete a contact |
|
||||
|
||||
### Dependencies
|
||||
|
||||
- vCard parsing/generation library (e.g., `vcard-rs` or similar)
|
||||
- XML processing (for CardDAV protocol)
|
||||
- Database access (PostgreSQL)
|
||||
- WebDAV base functionality
|
||||
|
||||
## Resources Required
|
||||
|
||||
- Developer time: 1 full-time developer for 5 weeks
|
||||
- Testing resources: Multiple CardDAV clients (Apple Contacts, Thunderbird, Android)
|
||||
- Server resources: Test environment with PostgreSQL
|
||||
|
||||
## Success Criteria
|
||||
|
||||
The implementation will be considered successful when:
|
||||
|
||||
1. Users can create, update, and delete address books
|
||||
2. Contacts can be managed within address books
|
||||
3. Address books can be shared between users
|
||||
4. Standard CardDAV clients can synchronize with the server
|
||||
5. Performance is acceptable with large address books (1000+ contacts)
|
||||
6. Security measures are properly implemented
|
||||
|
||||
## Client Setup Guides
|
||||
|
||||
After implementation, we will create setup guides for:
|
||||
|
||||
- Apple Contacts (macOS/iOS)
|
||||
- Thunderbird/Evolution
|
||||
- Android (using DAVx⁵)
|
||||
- Other common CardDAV clients
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
After the initial implementation, we may consider:
|
||||
|
||||
1. Advanced contact search capabilities
|
||||
2. Contact merging for duplicate detection
|
||||
3. Bulk import/export options
|
||||
4. Contact photo management
|
||||
5. Extended fields for specialized contact information
|
||||
6. Integration with other systems (e.g., LDAP directories)
|
||||
@@ -0,0 +1,363 @@
|
||||
# CardDAV Integration Technical Specification
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines the technical specification for implementing CardDAV support in OxiCloud, allowing users to synchronize their contacts across various devices and applications.
|
||||
|
||||
CardDAV (Card Distributed Authoring and Versioning) is an address book client/server protocol designed to allow users to access and share contact data on a server. It's an extension of WebDAV (RFC 4918) and is defined in RFC 6352.
|
||||
|
||||
## Architecture
|
||||
|
||||
The CardDAV implementation will follow the established hexagonal architecture pattern used throughout OxiCloud:
|
||||
|
||||
```
|
||||
┌───────────────────┐ ┌────────────────────┐ ┌────────────────────┐
|
||||
│ │ │ │ │ │
|
||||
│ Interfaces │ │ Application │ │ Infrastructure │
|
||||
│ - CardDAV API │────▶│ - Contact Service │────▶│ - Contact Repo │
|
||||
│ - Contact API │ │ - CardDAV Adapter │ │ - PG Repository │
|
||||
│ │ │ │ │ │
|
||||
└───────────────────┘ └────────────────────┘ └────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────┐
|
||||
│ │
|
||||
│ Domain │
|
||||
│ - Contact Entity │
|
||||
│ - Address Book │
|
||||
│ │
|
||||
└────────────────────┘
|
||||
```
|
||||
|
||||
### Components
|
||||
|
||||
1. **Domain Layer**
|
||||
- `Contact` entity - Represents a contact with properties like name, email, phone, etc.
|
||||
- `AddressBook` entity - Represents a collection of contacts
|
||||
- Repository interfaces for contact management
|
||||
|
||||
2. **Application Layer**
|
||||
- `ContactService` - Business logic for managing contacts
|
||||
- `CardDAVAdapter` - Converts between CardDAV protocol requests/responses and domain objects
|
||||
|
||||
3. **Infrastructure Layer**
|
||||
- `ContactPgRepository` - PostgreSQL implementation of contact repositories
|
||||
- `AddressBookPgRepository` - PostgreSQL implementation of address book repositories
|
||||
|
||||
4. **Interface Layer**
|
||||
- REST API endpoints for contact management
|
||||
- CardDAV protocol endpoints (WebDAV extension)
|
||||
|
||||
## Database Schema
|
||||
|
||||
The following database schema will be used to store contact information:
|
||||
|
||||
```sql
|
||||
-- Address books table
|
||||
CREATE TABLE IF NOT EXISTS carddav.address_books (
|
||||
id UUID PRIMARY KEY,
|
||||
name VARCHAR(255) NOT NULL,
|
||||
owner_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
|
||||
description TEXT,
|
||||
color VARCHAR(50),
|
||||
is_public BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE(owner_id, name)
|
||||
);
|
||||
|
||||
-- Address book sharing
|
||||
CREATE TABLE IF NOT EXISTS carddav.address_book_shares (
|
||||
address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
|
||||
user_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
|
||||
can_write BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
PRIMARY KEY(address_book_id, user_id)
|
||||
);
|
||||
|
||||
-- Contacts table
|
||||
CREATE TABLE IF NOT EXISTS carddav.contacts (
|
||||
id UUID PRIMARY KEY,
|
||||
address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
|
||||
uid VARCHAR(255) NOT NULL,
|
||||
full_name VARCHAR(255),
|
||||
first_name VARCHAR(255),
|
||||
last_name VARCHAR(255),
|
||||
nickname VARCHAR(255),
|
||||
email JSONB,
|
||||
phone JSONB,
|
||||
address JSONB,
|
||||
organization VARCHAR(255),
|
||||
title VARCHAR(255),
|
||||
notes TEXT,
|
||||
photo_url TEXT,
|
||||
birthday DATE,
|
||||
anniversary DATE,
|
||||
vcard TEXT NOT NULL,
|
||||
etag VARCHAR(255) NOT NULL,
|
||||
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE(address_book_id, uid)
|
||||
);
|
||||
|
||||
-- Contact groups
|
||||
CREATE TABLE IF NOT EXISTS carddav.contact_groups (
|
||||
id UUID PRIMARY KEY,
|
||||
address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
|
||||
name VARCHAR(255) NOT NULL,
|
||||
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
|
||||
-- Group memberships
|
||||
CREATE TABLE IF NOT EXISTS carddav.group_memberships (
|
||||
group_id UUID NOT NULL REFERENCES carddav.contact_groups(id) ON DELETE CASCADE,
|
||||
contact_id UUID NOT NULL REFERENCES carddav.contacts(id) ON DELETE CASCADE,
|
||||
PRIMARY KEY(group_id, contact_id)
|
||||
);
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### REST API
|
||||
|
||||
The following REST endpoints will be implemented for managing contacts:
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/address-books` | List all address books |
|
||||
| POST | `/api/address-books` | Create a new address book |
|
||||
| GET | `/api/address-books/:id` | Get a specific address book |
|
||||
| PUT | `/api/address-books/:id` | Update an address book |
|
||||
| DELETE | `/api/address-books/:id` | Delete an address book |
|
||||
| GET | `/api/address-books/:id/contacts` | List contacts in an address book |
|
||||
| POST | `/api/address-books/:id/contacts` | Create a new contact |
|
||||
| GET | `/api/address-books/:id/contacts/:contactId` | Get a specific contact |
|
||||
| PUT | `/api/address-books/:id/contacts/:contactId` | Update a contact |
|
||||
| DELETE | `/api/address-books/:id/contacts/:contactId` | Delete a contact |
|
||||
| GET | `/api/address-books/:id/groups` | List contact groups |
|
||||
| POST | `/api/address-books/:id/groups` | Create a new contact group |
|
||||
|
||||
### CardDAV Protocol Endpoints
|
||||
|
||||
The following CardDAV protocol endpoints will be implemented:
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| PROPFIND | `/carddav/` | List all address books |
|
||||
| PROPFIND | `/carddav/:addressBookId/` | Get address book information |
|
||||
| REPORT | `/carddav/:addressBookId/` | Query contacts in an address book |
|
||||
| GET | `/carddav/:addressBookId/:contactId.vcf` | Get a specific contact (vCard) |
|
||||
| PUT | `/carddav/:addressBookId/:contactId.vcf` | Create or update a contact |
|
||||
| DELETE | `/carddav/:addressBookId/:contactId.vcf` | Delete a contact |
|
||||
| MKCOL | `/carddav/:addressBookId/` | Create a new address book |
|
||||
| DELETE | `/carddav/:addressBookId/` | Delete an address book |
|
||||
|
||||
## Data Model
|
||||
|
||||
### Contact Entity
|
||||
|
||||
```rust
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct Contact {
|
||||
pub id: Uuid,
|
||||
pub address_book_id: Uuid,
|
||||
pub uid: String,
|
||||
pub full_name: Option<String>,
|
||||
pub first_name: Option<String>,
|
||||
pub last_name: Option<String>,
|
||||
pub nickname: Option<String>,
|
||||
pub email: Vec<Email>,
|
||||
pub phone: Vec<Phone>,
|
||||
pub address: Vec<Address>,
|
||||
pub organization: Option<String>,
|
||||
pub title: Option<String>,
|
||||
pub notes: Option<String>,
|
||||
pub photo_url: Option<String>,
|
||||
pub birthday: Option<NaiveDate>,
|
||||
pub anniversary: Option<NaiveDate>,
|
||||
pub vcard: String,
|
||||
pub etag: String,
|
||||
pub created_at: DateTime<Utc>,
|
||||
pub updated_at: DateTime<Utc>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct Email {
|
||||
pub email: String,
|
||||
pub r#type: String, // home, work, other
|
||||
pub is_primary: bool,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct Phone {
|
||||
pub number: String,
|
||||
pub r#type: String, // mobile, home, work, fax, other
|
||||
pub is_primary: bool,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct Address {
|
||||
pub street: Option<String>,
|
||||
pub city: Option<String>,
|
||||
pub state: Option<String>,
|
||||
pub postal_code: Option<String>,
|
||||
pub country: Option<String>,
|
||||
pub r#type: String, // home, work, other
|
||||
pub is_primary: bool,
|
||||
}
|
||||
```
|
||||
|
||||
### AddressBook Entity
|
||||
|
||||
```rust
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct AddressBook {
|
||||
pub id: Uuid,
|
||||
pub name: String,
|
||||
pub owner_id: String,
|
||||
pub description: Option<String>,
|
||||
pub color: Option<String>,
|
||||
pub is_public: bool,
|
||||
pub created_at: DateTime<Utc>,
|
||||
pub updated_at: DateTime<Utc>,
|
||||
}
|
||||
```
|
||||
|
||||
## Repositories
|
||||
|
||||
### Contact Repository Interface
|
||||
|
||||
```rust
|
||||
#[async_trait]
|
||||
pub trait ContactRepository: Send + Sync + 'static {
|
||||
async fn create_contact(&self, contact: Contact) -> ContactRepositoryResult<Contact>;
|
||||
async fn update_contact(&self, contact: Contact) -> ContactRepositoryResult<Contact>;
|
||||
async fn delete_contact(&self, id: &Uuid) -> ContactRepositoryResult<()>;
|
||||
async fn get_contact_by_id(&self, id: &Uuid) -> ContactRepositoryResult<Option<Contact>>;
|
||||
async fn get_contact_by_uid(&self, address_book_id: &Uuid, uid: &str) -> ContactRepositoryResult<Option<Contact>>;
|
||||
async fn get_contacts_by_address_book(&self, address_book_id: &Uuid) -> ContactRepositoryResult<Vec<Contact>>;
|
||||
async fn get_contacts_by_email(&self, email: &str) -> ContactRepositoryResult<Vec<Contact>>;
|
||||
async fn get_contacts_by_group(&self, group_id: &Uuid) -> ContactRepositoryResult<Vec<Contact>>;
|
||||
}
|
||||
```
|
||||
|
||||
### AddressBook Repository Interface
|
||||
|
||||
```rust
|
||||
#[async_trait]
|
||||
pub trait AddressBookRepository: Send + Sync + 'static {
|
||||
async fn create_address_book(&self, address_book: AddressBook) -> AddressBookRepositoryResult<AddressBook>;
|
||||
async fn update_address_book(&self, address_book: AddressBook) -> AddressBookRepositoryResult<AddressBook>;
|
||||
async fn delete_address_book(&self, id: &Uuid) -> AddressBookRepositoryResult<()>;
|
||||
async fn get_address_book_by_id(&self, id: &Uuid) -> AddressBookRepositoryResult<Option<AddressBook>>;
|
||||
async fn get_address_books_by_owner(&self, owner_id: &str) -> AddressBookRepositoryResult<Vec<AddressBook>>;
|
||||
async fn get_shared_address_books(&self, user_id: &str) -> AddressBookRepositoryResult<Vec<AddressBook>>;
|
||||
async fn get_public_address_books(&self) -> AddressBookRepositoryResult<Vec<AddressBook>>;
|
||||
async fn share_address_book(&self, address_book_id: &Uuid, user_id: &str, can_write: bool) -> AddressBookRepositoryResult<()>;
|
||||
async fn unshare_address_book(&self, address_book_id: &Uuid, user_id: &str) -> AddressBookRepositoryResult<()>;
|
||||
async fn get_address_book_shares(&self, address_book_id: &Uuid) -> AddressBookRepositoryResult<Vec<(String, bool)>>;
|
||||
}
|
||||
```
|
||||
|
||||
## CardDAV Protocol Implementation
|
||||
|
||||
The CardDAV implementation will support the following features:
|
||||
|
||||
1. **Address Book Discovery** - Allow clients to discover available address books
|
||||
2. **Address Book Collection** - Manage contacts within address books
|
||||
3. **vCard Support** - Store and retrieve contacts in vCard format (3.0 and 4.0)
|
||||
4. **Query Support** - Filter contacts by properties
|
||||
5. **Multiget Support** - Retrieve multiple contacts in a single request
|
||||
6. **Sync-Collection** - Efficient synchronization of changes
|
||||
|
||||
### CardDAV Adapter
|
||||
|
||||
The CardDAV adapter will handle:
|
||||
|
||||
1. Parsing CardDAV XML requests
|
||||
2. Converting between vCard and Contact entities
|
||||
3. Generating CardDAV XML responses
|
||||
4. Supporting PROPFIND, REPORT, and other WebDAV methods
|
||||
5. Implementing the proper WebDAV properties for CardDAV
|
||||
|
||||
## Integration Points
|
||||
|
||||
The CardDAV implementation will integrate with:
|
||||
|
||||
1. **Authentication System** - Reuse existing auth mechanisms
|
||||
2. **WebDAV Infrastructure** - Extend the existing WebDAV implementation
|
||||
3. **Database Layer** - Store contacts in PostgreSQL
|
||||
4. **User Management** - Connect contacts with user accounts
|
||||
|
||||
## Client Compatibility
|
||||
|
||||
The implementation should be compatible with the following clients:
|
||||
|
||||
- Apple Contacts
|
||||
- Google Contacts
|
||||
- Thunderbird
|
||||
- Outlook
|
||||
- Android DAVx⁵
|
||||
- iOS native contacts app
|
||||
- Evolution
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
The implementation will be divided into the following phases:
|
||||
|
||||
### Phase 1: Core Infrastructure
|
||||
- Database schema creation
|
||||
- Entity definitions
|
||||
- Repository interfaces
|
||||
- Basic DTO and port definitions
|
||||
|
||||
### Phase 2: Core Business Logic
|
||||
- Address book management service
|
||||
- Contact management service
|
||||
- vCard parsing and generation
|
||||
|
||||
### Phase 3: REST API
|
||||
- Address book endpoints
|
||||
- Contact management endpoints
|
||||
- Contact group endpoints
|
||||
|
||||
### Phase 4: CardDAV Protocol
|
||||
- CardDAV adapter implementation
|
||||
- WebDAV method handlers
|
||||
- XML parsing and generation
|
||||
- Protocol compliance testing
|
||||
|
||||
### Phase 5: Testing and Refinement
|
||||
- Integration testing with client applications
|
||||
- Performance optimization
|
||||
- Edge case handling
|
||||
|
||||
## Security Considerations
|
||||
|
||||
The CardDAV implementation must address the following security concerns:
|
||||
|
||||
1. **Authentication** - Ensure proper authentication for all operations
|
||||
2. **Authorization** - Verify permissions for each address book operation
|
||||
3. **Data Validation** - Validate vCard input to prevent injection attacks
|
||||
4. **Resource Limits** - Implement limits to prevent abuse
|
||||
5. **Error Handling** - Provide appropriate error responses without revealing sensitive information
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
To ensure good performance:
|
||||
|
||||
1. **Indexing** - Proper database indexes for contact queries
|
||||
2. **Caching** - Cache frequently accessed address books and contacts
|
||||
3. **Pagination** - Support pagination for large address books
|
||||
4. **Incremental Sync** - Efficient synchronization with client devices
|
||||
5. **ETags** - Use ETags to prevent unnecessary data transfers
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
The CardDAV implementation will be tested using:
|
||||
|
||||
1. **Unit Tests** - Test individual components in isolation
|
||||
2. **Integration Tests** - Test the interaction between components
|
||||
3. **Protocol Compliance Tests** - Verify adherence to the CardDAV specification
|
||||
4. **Client Compatibility Tests** - Test with various CardDAV clients
|
||||
5. **Performance Tests** - Measure performance with large address books
|
||||
+218
-90
@@ -1,12 +1,21 @@
|
||||
# WebDAV Client Setup Guide for OxiCloud
|
||||
# DAV Client Setup Guide for OxiCloud
|
||||
|
||||
This document provides detailed instructions for connecting desktop clients to OxiCloud using WebDAV, enabling seamless integration with your operating system's file browser.
|
||||
This document provides detailed instructions for connecting clients to OxiCloud using WebDAV, CalDAV, and CardDAV protocols, enabling seamless integration with your operating system's file browser, calendar, and contacts applications.
|
||||
|
||||
## What is WebDAV?
|
||||
## Table of Contents
|
||||
|
||||
WebDAV (Web Distributed Authoring and Versioning) is an extension of the HTTP protocol that allows users to collaboratively edit and manage files on remote web servers. OxiCloud implements WebDAV to provide desktop access to your files and folders.
|
||||
- [WebDAV Setup](#webdav-setup) (File Access)
|
||||
- [CalDAV Setup](#caldav-setup) (Calendar Synchronization)
|
||||
- [CardDAV Setup](#carddav-setup) (Contact Synchronization)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Connection Information
|
||||
---
|
||||
|
||||
## WebDAV Setup
|
||||
|
||||
WebDAV (Web Distributed Authoring and Versioning) is an extension of the HTTP protocol that allows users to collaboratively edit and manage files on remote web servers.
|
||||
|
||||
### Connection Information
|
||||
|
||||
Use the following details to connect to OxiCloud via WebDAV:
|
||||
|
||||
@@ -14,8 +23,6 @@ Use the following details to connect to OxiCloud via WebDAV:
|
||||
- **Username**: Your OxiCloud username
|
||||
- **Password**: Your OxiCloud password
|
||||
|
||||
## Client Setup Instructions
|
||||
|
||||
### Windows
|
||||
|
||||
#### Windows 10/11 (File Explorer)
|
||||
@@ -96,61 +103,208 @@ To automatically mount at boot, add to `/etc/fstab`:
|
||||
https://[your-oxicloud-server]/webdav/ /mnt/oxicloud davfs user,rw,auto 0 0
|
||||
```
|
||||
|
||||
### Mobile Devices
|
||||
---
|
||||
|
||||
## CalDAV Setup
|
||||
|
||||
CalDAV is an extension of WebDAV specifically designed for calendar access, allowing you to synchronize calendars between different devices and applications.
|
||||
|
||||
### Apple Calendar (macOS/iOS)
|
||||
|
||||
#### macOS:
|
||||
|
||||
1. Open the Calendar app
|
||||
2. Go to **Calendar** > **Add Account** > **Other CalDAV Account**
|
||||
3. Enter the following information:
|
||||
- **Account Type**: Advanced
|
||||
- **Username**: Your OxiCloud username
|
||||
- **Password**: Your OxiCloud password
|
||||
- **Server Address**: `https://[your-oxicloud-server]/caldav`
|
||||
4. Click **Sign In**
|
||||
5. Select the calendars you want to sync and click **Done**
|
||||
|
||||
#### iOS:
|
||||
|
||||
1. Go to **Settings** > **Calendar** > **Accounts** > **Add Account** > **Other**
|
||||
2. Tap **Add CalDAV Account**
|
||||
3. Enter the following information:
|
||||
- **Server**: `https://[your-oxicloud-server]/caldav`
|
||||
- **Username**: Your OxiCloud username
|
||||
- **Password**: Your OxiCloud password
|
||||
- **Description**: OxiCloud Calendar (or any name you prefer)
|
||||
4. Tap **Next**
|
||||
5. Turn on **Calendars** and tap **Save**
|
||||
|
||||
### Thunderbird with Lightning
|
||||
|
||||
1. Open Thunderbird and go to the **Calendar** tab
|
||||
2. Right-click in the left pane and select **New Calendar**
|
||||
3. Select **On the Network** and click **Next**
|
||||
4. Choose **CalDAV** as the format
|
||||
5. Enter the location: `https://[your-oxicloud-server]/caldav/calendars/your-calendar-id`
|
||||
6. Click **Next**
|
||||
7. Enter a name for the calendar and choose a color
|
||||
8. Click **Next** and then **Finish**
|
||||
9. When prompted, enter your OxiCloud username and password
|
||||
|
||||
### Android (DAVx⁵)
|
||||
|
||||
1. Install [DAVx⁵](https://play.google.com/store/apps/details?id=at.bitfire.davdroid) from Google Play Store
|
||||
2. Open DAVx⁵ and tap the **+** button
|
||||
3. Select **Login with URL and username**
|
||||
4. Enter the following information:
|
||||
- **Base URL**: `https://[your-oxicloud-server]/caldav`
|
||||
- **Username**: Your OxiCloud username
|
||||
- **Password**: Your OxiCloud password
|
||||
5. Tap **Connect**
|
||||
6. Select the calendars you want to sync
|
||||
7. Tap the checkbox to enable syncing
|
||||
|
||||
### Windows (Outlook)
|
||||
|
||||
1. Download and install [CalDAV Synchronizer](https://caldavsynchronizer.org/)
|
||||
2. Open Outlook and navigate to the **CalDAV Synchronizer** tab
|
||||
3. Click **Synchronization Profiles**
|
||||
4. Click **Add** to create a new profile
|
||||
5. Enter the following information:
|
||||
- **Profile Name**: OxiCloud Calendar (or any name you prefer)
|
||||
- **CalDAV URL**: `https://[your-oxicloud-server]/caldav/calendars/your-calendar-id`
|
||||
- **Username**: Your OxiCloud username
|
||||
- **Password**: Your OxiCloud password
|
||||
6. Click **Test or discover settings**
|
||||
7. Select the Outlook calendar to sync with
|
||||
8. Click **OK** to save the profile
|
||||
|
||||
---
|
||||
|
||||
## CardDAV Setup
|
||||
|
||||
CardDAV is an extension of WebDAV for address book access, allowing you to synchronize contacts between different devices and applications.
|
||||
|
||||
### Apple Contacts (macOS/iOS)
|
||||
|
||||
#### macOS:
|
||||
|
||||
1. Open the Contacts app
|
||||
2. Go to **Contacts** > **Add Account** > **Other contacts account**
|
||||
3. Select **CardDAV account**
|
||||
4. Enter the following information:
|
||||
- **Server**: `https://[your-oxicloud-server]/carddav`
|
||||
- **Username**: Your OxiCloud username
|
||||
- **Password**: Your OxiCloud password
|
||||
- **Description**: OxiCloud Contacts (or any name you prefer)
|
||||
5. Click **Sign In**
|
||||
|
||||
#### iOS:
|
||||
|
||||
1. Go to **Settings** > **Contacts** > **Accounts** > **Add Account** > **Other**
|
||||
2. Tap **Add CardDAV Account**
|
||||
3. Enter the following information:
|
||||
- **Server**: `https://[your-oxicloud-server]/carddav`
|
||||
- **Username**: Your OxiCloud username
|
||||
- **Password**: Your OxiCloud password
|
||||
- **Description**: OxiCloud Contacts (or any name you prefer)
|
||||
4. Tap **Next**
|
||||
5. Turn on **Contacts** and tap **Save**
|
||||
|
||||
### Thunderbird
|
||||
|
||||
1. Open Thunderbird and go to the **Address Book**
|
||||
2. Click on **Tools** > **Address Book**
|
||||
3. Go to **File** > **New** > **Remote Address Book**
|
||||
4. Enter the following information:
|
||||
- **Name**: OxiCloud Contacts (or any name you prefer)
|
||||
- **URL**: `https://[your-oxicloud-server]/carddav/address-books/your-address-book-id`
|
||||
5. Click **OK**
|
||||
6. When prompted, enter your OxiCloud username and password
|
||||
|
||||
### Android (DAVx⁵)
|
||||
|
||||
1. Install [DAVx⁵](https://play.google.com/store/apps/details?id=at.bitfire.davdroid) from Google Play Store
|
||||
2. Open DAVx⁵ and tap the **+** button
|
||||
3. Select **Login with URL and username**
|
||||
4. Enter the following information:
|
||||
- **Base URL**: `https://[your-oxicloud-server]/carddav`
|
||||
- **Username**: Your OxiCloud username
|
||||
- **Password**: Your OxiCloud password
|
||||
5. Tap **Connect**
|
||||
6. Select the address books you want to sync
|
||||
7. Tap the checkbox to enable syncing
|
||||
|
||||
### Windows (Outlook)
|
||||
|
||||
1. Download and install [CardDAV Synchronizer](https://caldavsynchronizer.org/) (same tool as for CalDAV)
|
||||
2. Open Outlook and navigate to the **CardDAV Synchronizer** tab
|
||||
3. Click **Synchronization Profiles**
|
||||
4. Click **Add** to create a new profile
|
||||
5. Select **CardDAV** as the synchronization resource
|
||||
6. Enter the following information:
|
||||
- **Profile Name**: OxiCloud Contacts (or any name you prefer)
|
||||
- **CardDAV URL**: `https://[your-oxicloud-server]/carddav/address-books/your-address-book-id`
|
||||
- **Username**: Your OxiCloud username
|
||||
- **Password**: Your OxiCloud password
|
||||
7. Click **Test or discover settings**
|
||||
8. Select the Outlook contacts folder to sync with
|
||||
9. Click **OK** to save the profile
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### WebDAV Connection Issues
|
||||
|
||||
- Verify the server URL is correct and includes the `/webdav/` path
|
||||
- Ensure your username and password are entered correctly
|
||||
- Check if your network blocks WebDAV connections (ports 80/443)
|
||||
- Verify that your OxiCloud server has WebDAV enabled
|
||||
|
||||
#### Calendar/Contact Sync Issues
|
||||
|
||||
- Verify the server URL is correct and includes the full path (`/caldav` or `/carddav`)
|
||||
- Check that your OxiCloud server is accessible from your network
|
||||
- Verify that your username and password are correct
|
||||
- Check that the calendar or address book ID is correct
|
||||
- Verify you have proper permissions to access the resource
|
||||
|
||||
#### Calendar Not Showing
|
||||
|
||||
- Verify the calendar is enabled in your client
|
||||
- Check if the calendar is shared with your account
|
||||
- Ensure your client supports the CalDAV protocol version
|
||||
|
||||
#### Contact Photos Not Syncing
|
||||
|
||||
- Some clients have limitations with contact photo syncing
|
||||
- Verify the photo is in a supported format (usually JPEG)
|
||||
- Check the size of the photo (some clients limit photo size)
|
||||
|
||||
### Client-Specific Issues
|
||||
|
||||
#### Windows File Explorer
|
||||
|
||||
For WebDAV issues on Windows:
|
||||
- Make sure the WebClient service is running
|
||||
- Increase timeout values in the registry
|
||||
- Try using a third-party WebDAV client like Cyberduck
|
||||
|
||||
#### iOS Devices
|
||||
|
||||
- If you're having trouble connecting, try going to **Settings** > **Accounts & Passwords** and manually add the account from there
|
||||
- For persistent issues, remove the account and add it again
|
||||
|
||||
#### Android
|
||||
|
||||
Several apps support WebDAV connections on Android:
|
||||
- DAVx⁵ requires battery optimization to be disabled for reliable background sync
|
||||
- Go to **Settings** > **Apps** > **DAVx⁵** > **Battery** > **Unrestricted**
|
||||
|
||||
1. **X-plore File Manager**:
|
||||
- Install from Google Play Store
|
||||
- Tap the globe icon (Network)
|
||||
- Select "New Connection" > "WebDAV"
|
||||
- Enter server details and credentials
|
||||
#### Outlook
|
||||
|
||||
2. **Total Commander** with WebDAV plugin:
|
||||
- Install both from Google Play Store
|
||||
- Open the app and tap the folder icon
|
||||
- Choose "LAN/Cloud" > "WebDAV"
|
||||
- Enter your server details and credentials
|
||||
- Make sure you have the latest version of CalDAV/CardDAV Synchronizer
|
||||
- The plugin might need to be reactivated after Outlook updates
|
||||
|
||||
#### iOS
|
||||
|
||||
1. **Documents by Readdle**:
|
||||
- Install from App Store
|
||||
- Tap the "+" button
|
||||
- Select "Add Connection" > "WebDAV Server"
|
||||
- Enter server URL and credentials
|
||||
|
||||
2. **FileBrowser**:
|
||||
- Install from App Store
|
||||
- Tap "+" to add a new connection
|
||||
- Select "WebDAV"
|
||||
- Enter server details and credentials
|
||||
|
||||
## Third-Party Applications
|
||||
|
||||
### Microsoft Office
|
||||
|
||||
1. Open any Office application
|
||||
2. Go to File > Open
|
||||
3. Click "Add a Place" and select "Office.com" or "SharePoint"
|
||||
4. Enter the WebDAV URL: `https://[your-oxicloud-server]/webdav/`
|
||||
5. Enter your credentials when prompted
|
||||
|
||||
### LibreOffice
|
||||
|
||||
1. Go to File > Open
|
||||
2. In the file dialog, enter the WebDAV URL in the location bar
|
||||
3. Enter credentials when prompted
|
||||
|
||||
### Desktop WebDAV Clients
|
||||
|
||||
- **Cyberduck** (Windows, macOS): Free, open-source WebDAV client
|
||||
- **WinSCP** (Windows): Primarily an FTP client, but supports WebDAV
|
||||
- **FileZilla Pro** (Windows, macOS, Linux): Supports WebDAV in the Pro version
|
||||
|
||||
## Performance Considerations
|
||||
### Performance Considerations
|
||||
|
||||
For optimal performance when using WebDAV:
|
||||
|
||||
@@ -158,39 +312,13 @@ For optimal performance when using WebDAV:
|
||||
2. **Slow Connections**: Enable offline caching in your client when available
|
||||
3. **File Locking**: Some clients support WebDAV locking to prevent conflicts
|
||||
|
||||
## Limitations and Known Issues
|
||||
### Getting Help
|
||||
|
||||
- **File Locking**: The current implementation does not support WebDAV locking operations (LOCK and UNLOCK)
|
||||
- **Performance**: WebDAV may be slower than native sync clients for large file transfers
|
||||
- **File Size**: Some WebDAV clients may have limitations on file sizes
|
||||
If you continue to experience issues, please:
|
||||
|
||||
## Security Considerations
|
||||
|
||||
WebDAV connections to OxiCloud use the same authentication mechanisms as the web interface. For enhanced security:
|
||||
|
||||
1. Always use HTTPS connections
|
||||
2. Consider setting up two-factor authentication if supported
|
||||
3. Don't save credentials on shared or public computers
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Issues
|
||||
|
||||
- Verify the server URL is correct and includes the `/webdav/` path
|
||||
- Ensure your username and password are entered correctly
|
||||
- Check if your network blocks WebDAV connections (ports 80/443)
|
||||
- Verify that your OxiCloud server has WebDAV enabled
|
||||
|
||||
### File Operation Issues
|
||||
|
||||
- If you cannot upload files, check if you have write permissions
|
||||
- If files appear to be corrupted, try using a different WebDAV client
|
||||
- For timeout errors, increase the client timeout settings if possible
|
||||
|
||||
### Client-Specific Issues
|
||||
|
||||
For client-specific issues, consult the documentation for your WebDAV client or operating system.
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues not covered in this document, please contact your OxiCloud administrator or refer to the main OxiCloud documentation.
|
||||
1. Check the OxiCloud logs for error messages
|
||||
2. Capture screenshots of the error messages
|
||||
3. Contact support with details about:
|
||||
- Your client application and version
|
||||
- Steps to reproduce the issue
|
||||
- Any error messages displayed
|
||||
Reference in New Issue
Block a user