Edouard Vanbelle
167 lines
12 KiB
Markdown
167 lines
12 KiB
Markdown
# 21 - WebDAV Technical Spec
|
|
|
|
OxiCloud's WebDAV implementation follows RFC 4918. Clients can perform file operations over HTTP, so desktop apps, mobile clients, and any WebDAV-compatible software can treat OxiCloud as a remote filesystem.
|
|
|
|
Supported operations: file/folder browsing, uploads, downloads, create/delete/move resources, metadata retrieval and modification.
|
|
|
|
## Architecture
|
|
|
|
The WebDAV layer follows the hexagonal architecture pattern used throughout the codebase:
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────────┐
|
|
│ INTERFACES │
|
|
│ │
|
|
│ ┌───────────────────────────────────────────────────────────┐ │
|
|
│ │ WebDAV Handler │ │
|
|
│ │ │ │
|
|
│ │ OPTIONS │ PROPFIND │ GET │ PUT │ DELETE │ MOVE │ COPY │ │
|
|
│ └─────────────────────────────┬─────────────────────────────┘ │
|
|
│ │ │
|
|
└─────────────────────────────────┼──────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ APPLICATION │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────┐ │
|
|
│ │ WebDAV Adapter │ │
|
|
│ │ │ │
|
|
│ │ XML Processing │ Protocol Translation │ DTOs Conversion │ │
|
|
│ └──────────────────────────────┬──────────────────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ │
|
|
│ ┌──────────────┐ ┌───────────────┐ ┌──────────────┐ ┌───────┐ │
|
|
│ │ │ │ │ │ │ │ │ │
|
|
│ │ FileService │ │ FolderService │ │ AuthService │ │ Other │ │
|
|
│ │ │ │ │ │ │ │ │ │
|
|
│ └──────┬───────┘ └───────┬───────┘ └──────┬───────┘ └───┬───┘ │
|
|
│ │ │ │ │ │
|
|
└─────────┼──────────────────┼─────────────────┼──────────────┼──────┘
|
|
│ │ │ │
|
|
▼ ▼ ▼ ▼
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ DOMAIN │
|
|
│ │
|
|
│ ┌──────────┐ ┌───────────┐ ┌───────────┐ ┌────────┐ ┌──────┐ │
|
|
│ │ │ │ │ │ │ │ │ │ │ │
|
|
│ │ File │ │ Folder │ │ User │ │ Share │ │ etc. │ │
|
|
│ │ │ │ │ │ │ │ │ │ │ │
|
|
│ └──────────┘ └───────────┘ └───────────┘ └────────┘ └──────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Key Components
|
|
|
|
1. **WebDAV Handler** (`src/interfaces/api/handlers/webdav_handler.rs`) -- processes HTTP requests for WebDAV methods, maps operations to service calls, manages response formatting.
|
|
|
|
2. **WebDAV Adapter** (`src/application/adapters/webdav_adapter.rs`) -- converts between WebDAV XML and domain objects, parses PROPFIND/PROPPATCH requests, generates XML responses.
|
|
|
|
## Data Flow
|
|
|
|
A typical WebDAV request flows through:
|
|
|
|
1. Client sends a WebDAV request (e.g., PROPFIND for directory listing)
|
|
2. **webdav_handler.rs** receives and authenticates
|
|
3. Handler identifies the operation type, passes to **WebDavAdapter**
|
|
4. Adapter parses XML, converts to domain objects
|
|
5. Handler calls appropriate service methods (e.g., **folder_service.list_folders()**)
|
|
6. Domain operations execute via existing services
|
|
7. Results go back to the adapter for XML formatting
|
|
8. Handler returns the response with proper HTTP headers
|
|
|
|
## Integration with OxiCloud
|
|
|
|
### File Operations
|
|
Uses **FileService** for uploads, downloads, and management.
|
|
|
|
### Folder Operations
|
|
Uses **FolderService** for directory listing and manipulation. Maintains consistent behavior with the REST API.
|
|
|
|
### Authentication
|
|
Same auth mechanisms as the rest of OxiCloud. Supports HTTP Basic Authentication for WebDAV clients.
|
|
|
|
### Trash Integration
|
|
Integrates with the trash system for file/folder deletion. WebDAV operations use the trash feature when available.
|
|
|
|
## Request Processing
|
|
|
|
### PROPFIND (Directory Listing)
|
|
|
|
```
|
|
┌─────────┐ ┌────────────────┐ ┌─────────────────┐ ┌───────────────┐
|
|
│ │ │ │ │ │ │ │
|
|
│ Client │────▶│ WebDAV Handler │────▶│ WebDAV Adapter │────▶│ FolderService │
|
|
│ │ │ │ │ │ │ │
|
|
└─────────┘ └────────────────┘ └─────────────────┘ └───────┬───────┘
|
|
│
|
|
┌─────────┐ ┌────────────────┐ ┌─────────────────┐ ┌───────▼───────┐
|
|
│ │ │ │ │ │ │ │
|
|
│ Client │◀────│ WebDAV Handler │◀────│ WebDAV Adapter │◀────│ FileService │
|
|
│ │ │ │ │ │ │ │
|
|
└─────────┘ └────────────────┘ └─────────────────┘ └───────────────┘
|
|
```
|
|
|
|
1. Client sends PROPFIND with Depth header
|
|
2. Handler extracts path and depth
|
|
3. Adapter parses XML to determine requested properties
|
|
4. **FolderService** retrieves folder contents
|
|
5. **FileService** retrieves file info if needed
|
|
6. Adapter generates XML response with all properties
|
|
7. Handler returns 207 Multi-Status
|
|
|
|
### PUT (File Upload)
|
|
|
|
```
|
|
┌─────────┐ ┌────────────────┐ ┌─────────────────┐
|
|
│ │ │ │ │ │
|
|
│ Client │────▶│ WebDAV Handler │────▶│ FileService │
|
|
│ │ │ │ │ │
|
|
└─────────┘ └────────────────┘ └─────────────────┘
|
|
│
|
|
┌─────────┐ ┌────────────────┐ ┌────────▼────────┐
|
|
│ │ │ │ │ │
|
|
│ Client │◀────│ WebDAV Handler │◀────│ Response │
|
|
│ │ │ │ │ │
|
|
└─────────┘ └────────────────┘ └─────────────────┘
|
|
```
|
|
|
|
1. Client sends PUT with file contents
|
|
2. Handler extracts path and parent folder info
|
|
3. **FileService** uploads the file
|
|
4. Handler returns 201 Created or 204 No Content
|
|
|
|
## Security
|
|
|
|
- **Authentication** -- same mechanisms as the REST API. Supports HTTP Basic Auth for WebDAV clients. Same permissions model applies.
|
|
- **Authorization** -- users can only access their own files through WebDAV. Shared resources keep the same permissions.
|
|
- **HTTPS** -- all WebDAV traffic should be served over HTTPS.
|
|
- **Input validation** -- all XML inputs strictly validated. Path traversal prevented by proper path normalization.
|
|
|
|
## Extension Points
|
|
|
|
1. **Property storage** -- support for custom WebDAV properties via a property database.
|
|
2. **CalDAV/CardDAV** -- the architecture allows extending to CalDAV (calendar) and CardDAV (contacts), both built on the WebDAV foundation.
|
|
3. **Advanced locking** -- full WebDAV locking for collaborative editing.
|
|
|
|
## Implementation Status
|
|
|
|
| Method | Status | Notes |
|
|
|-----------|-----------|------------------------------------------|
|
|
| OPTIONS | Complete | Advertises WebDAV capabilities |
|
|
| PROPFIND | Complete | Full directory listing with properties |
|
|
| GET | Complete | File download fully implemented |
|
|
| HEAD | Complete | Metadata retrieval implemented |
|
|
| PUT | Complete | File creation and update implemented |
|
|
| DELETE | Complete | Integration with trash features |
|
|
| MKCOL | Complete | Directory creation implemented |
|
|
| COPY | Complete | File/folder copying implemented |
|
|
| MOVE | Complete | File/folder moving/renaming implemented |
|
|
| PROPPATCH | Complete | Property updates implemented |
|
|
| LOCK | Complete | Basic locking capability implemented |
|
|
| UNLOCK | Complete | Basic unlocking capability implemented |
|
|
|
|
All WebDAV methods required by RFC 4918 are implemented. The server is compatible with all standard clients. Persistent property storage may be added later.
|