fixing db error and upgrading technical documentation
This commit is contained in:
Dionisio
@@ -0,0 +1,166 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user