arnef
2fd39c8180
Unify user data directory from fragmented layout to consistent nested format: - Move WebDAV from: data/files/<username> → data/<username>/files/ - Move CalDAV from: data/<username>/cal-<name> → data/<username>/calendars/<name> - Move CardDAV from: data/<username>/card-<name> → data/<username>/addressbooks/<name> Changes: - internal/store/store.go: Update collectionPath() to map collection names - internal/store/migrate.go: Add idempotent Migrate() method - internal/store/migrate_test.go: Comprehensive migration tests - internal/webdav/handler.go: Use new unified path structure - cmd/server/main.go: Auto-run migration on startup - tools/nidusctl/main.go: Add migrate subcommand - Update tests to verify new structure URL endpoints unchanged - only on-disk structure modified. All tests pass.
160 lines
4.5 KiB
Markdown
160 lines
4.5 KiB
Markdown
# Data Directory Structure Unification - Summary of Changes
|
|
|
|
## Overview
|
|
This change unifies the user data directory structure from a fragmented layout (with separate top-level `files/` directory) to a consistent nested format under each user's directory.
|
|
|
|
## Problem Statement
|
|
|
|
**Before**: Inconsistent directory structure
|
|
- WebDAV: `data/files/<username>/`
|
|
- CalDAV: `data/<username>/cal-<name>/`
|
|
- CardDAV: `data/<username>/card-<name>/`
|
|
|
|
**After**: Unified structure
|
|
- All data: `data/<username>/{files,calendars,addressbooks}/<name>/`
|
|
|
|
**Benefits**:
|
|
1. All user data in a single predictable location
|
|
2. Easier backups (single user directory instead of multiple paths)
|
|
3. Cleaner directory structure
|
|
4. Reduced code complexity in path resolution
|
|
|
|
## Implementation Details
|
|
|
|
### Files Modified
|
|
|
|
1. **`internal/store/store.go`**
|
|
- Updated `collectionPath()` to map collection names to new unified structure:
|
|
- `cal-<name>` → `<username>/calendars/<name>`
|
|
- `card-<name>` → `<username>/addressbooks/<name>`
|
|
- `files` → `<username>/files`
|
|
- Kept `sanitize()` for security
|
|
|
|
2. **`internal/store/migrate.go`** (new file)
|
|
- Added `Migrate()` method to restructure data directory
|
|
- Idempotent migration that handles both old and new structures
|
|
- Migrates WebDAV, CalDAV, and CardDAV data atomically
|
|
|
|
3. **`internal/store/migrate_test.go`** (new file)
|
|
- Comprehensive tests for migration functionality
|
|
- Covers migration, idempotency, and edge cases
|
|
|
|
4. **`internal/webdav/handler.go`**
|
|
- Updated WebDAV handler to use new unified path structure
|
|
- Changed from `dataDir/files/<username>` to `dataDir/<username>/files`
|
|
|
|
5. **`internal/webdav/handler_test.go`**
|
|
- Updated test assertions to check new path structure
|
|
- Changed from `dataDir/files/alice/` to `dataDir/alice/files/`
|
|
|
|
6. **`cmd/server/main.go`**
|
|
- Added automatic migration on server startup
|
|
- Ensures data directory is always in correct format
|
|
|
|
7. **`tools/migrate/main.go`** (new file)
|
|
- Standalone migration tool
|
|
- Can be run independently of server
|
|
|
|
8. **`tools/nidusctl/main.go`**
|
|
- Added `migrate` subcommand
|
|
- Integrated into existing admin CLI
|
|
|
|
### Path Mapping
|
|
|
|
| Old Path | New Path | Collection Type |
|
|
|----------|----------|-----------------|
|
|
| `files/<user>/<name>` | `<user>/files/<name>` | WebDAV |
|
|
| `<user>/cal-<name>/` | `<user>/calendars/<name>/` | CalDAV |
|
|
| `<user>/card-<name>/` | `<user>/addressbooks/<name>/` | CardDAV |
|
|
|
|
## Testing
|
|
|
|
All existing tests pass with the new structure:
|
|
- ✅ Store tests (path resolution, locking)
|
|
- ✅ CalDAV backend tests
|
|
- ✅ CardDAV backend tests
|
|
- ✅ WebDAV handler tests
|
|
- ✅ Web UI tests
|
|
- ✅ DB tests
|
|
- ✅ Migration tests (new)
|
|
|
|
Run tests:
|
|
```bash
|
|
go test ./... -v
|
|
go test ./internal/store/... -run TestMigrate -v
|
|
```
|
|
|
|
## Migration Process
|
|
|
|
### For Existing Installations
|
|
|
|
1. **Stop the server** (optional but recommended)
|
|
```bash
|
|
# Stop any running server
|
|
```
|
|
|
|
2. **Run migration**
|
|
```bash
|
|
go run ./tools/nidusctl -config config.yaml migrate
|
|
```
|
|
|
|
3. **Verify migration**
|
|
```bash
|
|
ls -la data/
|
|
# Should see user directories with unified structure
|
|
```
|
|
|
|
4. **Start the server**
|
|
```bash
|
|
go run ./cmd/server -config config.yaml
|
|
```
|
|
|
|
### For New Deployments
|
|
|
|
No migration needed - the new structure is used by default:
|
|
- Server creates `<username>/files/`, `<username>/calendars/`, etc.
|
|
- All data follows the unified structure from the start
|
|
|
|
## API Compatibility
|
|
|
|
**URL structure remains unchanged**:
|
|
- CalDAV: `/cal/`, `/cal/home/<name>/`, `/cal/home/<name>/<object>`
|
|
- CardDAV: `/card/`, `/card/home/<name>/`, `/card/home/<name>/<object>`
|
|
- WebDAV: `/files/`
|
|
|
|
Only the **on-disk path structure** changed. All HTTP endpoints and URL paths remain identical.
|
|
|
|
## Security
|
|
|
|
- Path sanitization maintained via `sanitize()` function
|
|
- No security-sensitive code changed
|
|
- Locking mechanism unchanged (still per-user)
|
|
- All same security checks apply
|
|
|
|
## Performance
|
|
|
|
No measurable performance impact:
|
|
- Same number of filesystem operations
|
|
- Same lock granularity (per-user)
|
|
- Same cache behavior
|
|
|
|
## Rollback
|
|
|
|
If rollback is needed:
|
|
1. Restore data directory from backup
|
|
2. Restart server (will migrate again on next startup)
|
|
|
|
## Future Considerations
|
|
|
|
This unified structure makes future enhancements easier:
|
|
- Easier to add per-user quotas
|
|
- Simpler backup/restore logic
|
|
- Better support for user-specific configuration
|
|
- Cleaner codebase with consistent patterns
|
|
|
|
## Documentation Updates
|
|
|
|
- `MIGRATION.md` - Detailed migration guide
|
|
- `CHANGES_SUMMARY.md` - This file
|
|
- Code comments updated to reflect new structure
|