nidus/CHANGES_SUMMARY.md

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:

go test ./... -v
go test ./internal/store/... -run TestMigrate -v

Migration Process

For Existing Installations

1. Stop the server (optional but recommended)

   # Stop any running server
   

2. Run migration

   go run ./tools/nidusctl -config config.yaml migrate
   

3. Verify migration

   ls -la data/
   # Should see user directories with unified structure
   

4. Start the server

   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