docs: remove CHANGES_SUMMARY.md (superseded by AGENTS.md)
This commit is contained in:
@@ -1,159 +0,0 @@
|
|||||||
# 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
|
|
||||||
Reference in New Issue
Block a user