Oxicloud/doc/webdav-technical-spec.md

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.