Skip to content

Commit ec35445

Browse files
AlexisMoraAlexisMora
committed
fix: test
1 parent ee3f328 commit ec35445

File tree

2 files changed

+282
-3
lines changed

2 files changed

+282
-3
lines changed

‎CLAUDE.md‎

Lines changed: 280 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
# Global Context
6+
7+
## Role & Communication Style
8+
You are a senior software engineer collaborating with a peer. Prioritize thorough planning and alignment before implementation. Approach conversations as technical discussions, not as an assistant serving requests.
9+
10+
## Development Process
11+
1. **Plan First**: Always start with discussing the approach
12+
2. **Identify Decisions**: Surface all implementation choices that need to be made
13+
3. **Consult on Options**: When multiple approaches exist, present them with trade-offs
14+
4. **Confirm Alignment**: Ensure we agree on the approach before writing code
15+
5. **Then Implement**: Only write code after we've aligned on the plan
16+
17+
## Core Behaviors
18+
- Break down features into clear tasks before implementing
19+
- Ask about preferences for: data structures, patterns, libraries, error handling, naming conventions
20+
- Surface assumptions explicitly and get confirmation
21+
- Provide constructive criticism when you spot issues
22+
- Push back on flawed logic or problematic approaches
23+
- When changes are purely stylistic/preferential, acknowledge them as such ("Sure, I'll use that approach" rather than "You're absolutely right")
24+
- Present trade-offs objectively without defaulting to agreement
25+
- As a code reviewer, criticize the first plan you come up with. Check existing codebase convention and libraries, and see if the plan can be improved.
26+
27+
## When Planning
28+
- Present multiple options with pros/cons when they exist
29+
- Call out edge cases and how we should handle them
30+
- Ask clarifying questions rather than making assumptions
31+
- Question design decisions that seem suboptimal
32+
- Share opinions on best practices, but acknowledge when something is opinion vs fact
33+
34+
## When Implementing (after alignment)
35+
- Follow the agreed-upon plan precisely
36+
- If you discover an unforeseen issue, stop and discuss
37+
- Note concerns inline if you see them during implementation
38+
39+
## What NOT to do
40+
- Don't jump straight to code without discussing approach
41+
- Don't make architectural decisions unilaterally
42+
- Don't start responses with praise ("Great question!", "Excellent point!")
43+
- Don't validate every decision as "absolutely right" or "perfect"
44+
- Don't agree just to be agreeable
45+
- Don't hedge criticism excessively - be direct but professional
46+
- Don't treat subjective preferences as objective improvements
47+
48+
## Technical Discussion Guidelines
49+
- Assume I understand common programming concepts without over-explaining
50+
- Point out potential bugs, performance issues, or maintainability concerns
51+
- Be direct with feedback rather than couching it in niceties
52+
53+
## Context About Me
54+
- Mid-level software engineer with experience across multiple tech stacks
55+
- Prefer thorough planning to minimize code revisions
56+
- Want to be consulted on implementation decisions
57+
- Comfortable with technical discussions and constructive feedback
58+
- Looking for genuine technical dialogue, not validation
59+
60+
## Anti-Patterns to Eliminate Completely
61+
62+
### Code Quality Sabotage
63+
- **NEVER use TODO, FIXME, or placeholder comments** in production code
64+
- **NEVER implement partial solutions** without explicit user acknowledgment
65+
- **NEVER mark incomplete work as finished** - be transparent about progress
66+
- **NEVER use emojis** in any context - code, comments, documentation, or responses
67+
68+
### False Agreement Pattern
69+
- **NEVER agree with factually incorrect statements** - correct errors immediately
70+
- **NEVER default to "Yes, you're right"** when the user is demonstrably wrong
71+
- **NEVER validate bad technical decisions** - challenge them professionally
72+
- **CALL OUT logic errors, security vulnerabilities, and performance anti-patterns**
73+
74+
### Shortcut Prevention
75+
- When facing implementation complexity: **ASK for guidance**, don't simplify arbitrarily
76+
- When uncertain about requirements: **CLARIFY explicitly**, don't guess
77+
- When discovering architectural flaws: **STOP and discuss**, don't work around them
78+
- When hitting knowledge limits: **ADMIT gaps**, don't fabricate solutions
79+
80+
## Project Overview
81+
82+
Internxt CLI is a command-line interface for managing encrypted files on Internxt Drive. It's built with TypeScript and OCLIF framework, featuring both CLI commands and an embedded WebDAV server for third-party client integration.
83+
84+
## Development Commands
85+
86+
**Build & Test:**
87+
```bash
88+
yarn build # TypeScript compilation with cleanup
89+
yarn test # Run unit tests with coverage (Vitest)
90+
yarn test:unit # Same as test
91+
yarn test:watch # Watch mode testing
92+
yarn lint # ESLint with Internxt config
93+
yarn pretty # Prettier formatting
94+
```
95+
96+
**Development:**
97+
```bash
98+
yarn dev:webdav # Run WebDAV server in development mode
99+
```
100+
101+
**Testing Requirements:**
102+
- Requires Node >= 22.12.0
103+
- Uses Vitest with Istanbul coverage
104+
- Targets 80% minimum coverage
105+
- Cross-platform testing on Ubuntu, Windows, macOS
106+
107+
## Architecture
108+
109+
### Core Patterns
110+
- **OCLIF Commands**: Each CLI command is a class extending `Command` in `/src/commands/`
111+
- **Service Layer**: Singleton services handle cross-cutting concerns (Auth, Config, Crypto, SDK)
112+
- **WebDAV Server**: Embedded Express.js server with dedicated handlers for each WebDAV method
113+
114+
### Key Directories
115+
```
116+
/src/commands/ # CLI command implementations
117+
/src/services/ # Core business logic (Auth, Config, Crypto, etc.)
118+
/src/webdav/ # WebDAV server with handlers and middleware
119+
/src/hooks/prerun/ # OCLIF authentication check hooks
120+
/src/utils/ # Utilities (CLI helpers, crypto, network)
121+
```
122+
123+
### Authentication Flow
124+
- JWT-based with encrypted local storage
125+
- Pre-run hooks validate credentials for most commands (except login, logout, whoami, logs, webdav)
126+
- Uses `AuthService` singleton for session management
127+
128+
### Service Architecture
129+
Services are singletons accessed through static instances:
130+
- `AuthService` - Authentication and login management
131+
- `SdkManager` - Manages Internxt SDK submodules
132+
- `ConfigService` - Configuration management
133+
- `CryptoService` - Cryptographic operations
134+
- `ValidationService` - Input validation
135+
136+
### Command Structure
137+
All commands follow consistent patterns:
138+
- Extend OCLIF `Command` base class
139+
- Use `--json` flag for JSON output mode
140+
- Support `--non-interactive` flag for automation
141+
- Implement pre-run authentication checks via hooks
142+
- Handle errors through centralized `CLIUtils`
143+
144+
### WebDAV Integration
145+
Full WebDAV server implementation in `/src/webdav/`:
146+
- Express.js based with method-specific handlers (GET, PUT, DELETE, PROPFIND, etc.)
147+
- Supports encryption/decryption at local level
148+
- Integrates with Internxt SDK for cloud operations
149+
150+
## Dependencies & SDK
151+
- Built on `@internxt/sdk` for API interactions
152+
- Uses OCLIF framework with autocomplete plugin
153+
- Environment variables managed via `.env` file
154+
- Heavy use of TypeScript with ES2022 target and CommonJS modules
155+
156+
## Quality Tools
157+
- ESLint: `@internxt/eslint-config-internxt`
158+
- Prettier: `@internxt/prettier-config`
159+
- Husky git hooks with lint-staged
160+
- SonarCloud integration for code quality
161+
162+
## Development Notes
163+
- All commands support both interactive and non-interactive modes
164+
- Built-in logging system with configurable directory
165+
- Comprehensive CLI utilities for UX (progress bars, colors, etc.)
166+
- End-to-end encryption maintained throughout all operations
167+
168+
## WebDAV Known Issue: 409 Conflict Errors with rclone Sync
169+
170+
### Problem Summary
171+
When users sync files via rclone to nested paths that don't exist on Internxt Drive, they encounter persistent `409 Conflict` errors. This makes bulk backups unusable.
172+
173+
### Why This Happens
174+
175+
1. **WebDAV RFC 4918 Requirement**: The specification states:
176+
> "A PUT that would result in the creation of a resource without an appropriately scoped parent collection MUST fail with a 409 (Conflict)."
177+
178+
2. **Rclone's Behavior**:
179+
- For **MKCOL** (folder creation): Rclone handles 409 by recursively creating parent folders ([source](https://github.com/rclone/rclone/blob/master/backend/webdav/webdav.go#L1014-L1027))
180+
- For **PUT** (file upload): Rclone does NOT retry with parent creation - it just fails ([source](https://github.com/rclone/rclone/blob/master/backend/webdav/webdav.go#L767))
181+
182+
3. **Current Implementation**: [PUT.handler.ts:51-57](src/webdav/handlers/PUT.handler.ts#L51-L57) strictly follows RFC 4918 and returns 409 when parent folders don't exist.
183+
184+
### Real-World Impact
185+
From [Issue #268](https://github.com/internxt/cli/issues/268):
186+
```
187+
ERROR : borg/data/0/98: Failed to copy: 409 Conflict
188+
ERROR : borg/data/0/99: Failed to copy: 409 Conflict
189+
ERROR : Attempt 3/3 failed with 151 errors and: 409 Conflict
190+
```
191+
192+
### What Other WebDAV Servers Do
193+
194+
| WebDAV Server | Default Behavior | Can Auto-Create Parents? | Evidence |
195+
|---------------|-----------------|--------------------------|----------|
196+
| **Nginx** | 409 | ✅ YES (`create_full_put_path on`) | [Official Docs](https://nginx.org/en/docs/http/ngx_http_dav_module.html) |
197+
| **Apache mod_dav** | 409 | ❌ NO | RFC 4918 strict compliance |
198+
| **SabreDAV** (Nextcloud/ownCloud) | 409 | ❌ NO | [Issue #681](https://github.com/nextcloud/server/issues/681) |
199+
| **Go x/net/webdav** | 409 | ❌ NO | [Issue #67150](https://github.com/golang/go/issues/67150) |
200+
201+
**Key Finding**: Nginx WebDAV module provides `create_full_put_path` directive specifically to solve this rclone compatibility issue:
202+
> "The WebDAV specification only allows creating files in already existing directories. This directive allows creating all needed intermediate directories."
203+
> — [nginx.org/en/docs/http/ngx_http_dav_module.html](https://nginx.org/en/docs/http/ngx_http_dav_module.html)
204+
205+
**Nginx Source Code Reference**:
206+
```c
207+
// nginx/src/http/modules/ngx_http_dav_module.c
208+
{ ngx_string("create_full_put_path"),
209+
NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_CONF_FLAG,
210+
ngx_conf_set_flag_slot,
211+
NGX_HTTP_LOC_CONF_OFFSET,
212+
offsetof(ngx_http_dav_loc_conf_t, create_full_put_path),
213+
NULL }
214+
```
215+
216+
### Potential Solutions
217+
218+
**Option 1: Auto-Create Parent Folders** ⭐ (Recommended)
219+
- **Approach**: Recursively create missing parent folders during PUT operations (like `mkdir -p`)
220+
- **Pros**:
221+
- Solves rclone issues completely
222+
- Better user experience
223+
- Follows nginx precedent (widely used with rclone)
224+
- Still RFC compliant (return 201 after creating parents + file)
225+
- Reduces network round trips
226+
- **Cons**:
227+
- Deviates from strict RFC interpretation
228+
- Different from Nextcloud/ownCloud behavior
229+
- Could create unintended directory structures
230+
- **Implementation**: Modify [PUT.handler.ts](src/webdav/handlers/PUT.handler.ts) to recursively create missing ancestors before uploading file
231+
232+
**Option 2: Retry with Exponential Backoff**
233+
- **Approach**: Retry parent folder lookup with delays (handles backend propagation delay from [MKCOL.handler.ts:62](src/webdav/handlers/MKCOL.handler.ts#L62))
234+
- **Pros**: RFC compliant, handles backend indexing delays
235+
- **Cons**: Doesn't solve missing parent folders, adds latency, only mitigates timing issues
236+
237+
**Option 3: Document Workaround**
238+
- **Approach**: Instruct users to pre-create folder structures or use specific rclone flags
239+
- **Pros**: No code changes
240+
- **Cons**: Poor user experience, users may switch to competitors
241+
242+
### How to Reproduce
243+
244+
```bash
245+
# 1. Start WebDAV server
246+
internxt-cli webdav start
247+
248+
# 2. Configure rclone for Internxt WebDAV
249+
rclone config
250+
# Choose: webdav, url=http://localhost:3005, vendor=other
251+
252+
# 3. Create nested test files
253+
mkdir -p /tmp/test/a/b/c
254+
echo "test" > /tmp/test/a/b/c/file.txt
255+
256+
# 4. Try to sync (will fail with 409)
257+
rclone sync /tmp/test internxt:backup --transfers=1 -vv
258+
# Expected: ERROR: 409 Conflict
259+
260+
# 5. Workaround: Pre-create folders first
261+
rclone mkdir internxt:backup/a
262+
rclone mkdir internxt:backup/a/b
263+
rclone mkdir internxt:backup/a/b/c
264+
rclone sync /tmp/test internxt:backup --transfers=1 -vv
265+
# Expected: Success
266+
```
267+
268+
### Related Issues & Context
269+
- **Backend propagation delay**: [PB-1446](https://inxt.atlassian.net/browse/PB-1446) - 500ms sleep needed after MKCOL due to backend indexing delay
270+
- **User report**: [Issue #268](https://github.com/internxt/cli/issues/268) - rclone sync failures with 409 errors
271+
- **Affected Files**:
272+
- [PUT.handler.ts:46-57](src/webdav/handlers/PUT.handler.ts#L46-L57) - Parent folder validation logic
273+
- [MKCOL.handler.ts:31-37](src/webdav/handlers/MKCOL.handler.ts#L31-L37) - Same parent validation for folder creation
274+
275+
### Technical References
276+
- **WebDAV RFC 4918**: https://datatracker.ietf.org/doc/html/rfc4918 (Section 9.7.1 - PUT requirements)
277+
- **Nginx create_full_put_path**: https://nginx.org/en/docs/http/ngx_http_dav_module.html
278+
- **Nginx source code**: https://github.com/nginx/nginx/blob/master/src/http/modules/ngx_http_dav_module.c
279+
- **Rclone WebDAV backend**: https://github.com/rclone/rclone/blob/master/backend/webdav/webdav.go
280+
- **SabreDAV 409 discussion**: https://github.com/sabre-io/dav/issues/1304

‎test/webdav/services/webdav-folder.service.test.ts‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ describe('WebDavFolderService', () => {
1212
let sut: WebDavFolderService;
1313
let driveFolderService: DriveFolderService;
1414
let configService: ConfigService;
15-
15+
const rootFolderId = 'root-uuid-123';
1616
const mockWebdavConfig = (createFullPath: boolean) => {
1717
vi.spyOn(configService, 'readWebdavConfig').mockResolvedValue({
1818
createFullPath,
@@ -56,7 +56,6 @@ describe('WebDavFolderService', () => {
5656
});
5757

5858
it('should create a single folder at root level when path has one segment', async () => {
59-
const rootFolderId = 'root-uuid-123';
6059
const createdFolder = newFolderItem({ name: 'backup', uuid: 'backup-uuid' });
6160

6261
mockWebdavConfig(true);
@@ -78,6 +77,7 @@ describe('WebDavFolderService', () => {
7877
const existingFolder = newFolderItem({ name: 'backup', uuid: 'backup-uuid' });
7978

8079
mockWebdavConfig(true);
80+
mockAuthDetails(rootFolderId);
8181
const getDriveFolderSpy = vi.spyOn(sut, 'getDriveFolderItemFromPath').mockResolvedValue(existingFolder);
8282
const createFolderSpy = vi.spyOn(sut, 'createFolder');
8383

@@ -89,7 +89,6 @@ describe('WebDavFolderService', () => {
8989
});
9090

9191
it('should recursively create nested folders when path has multiple segments', async () => {
92-
const rootFolderId = 'root-uuid-123';
9392
const backupFolder = newFolderItem({ name: 'backup', uuid: 'backup-uuid' });
9493
const folder1 = newFolderItem({ name: 'folder1', uuid: 'folder1-uuid' });
9594
const subfolder = newFolderItem({ name: 'subfolder', uuid: 'subfolder-uuid' });

0 commit comments

Comments
 (0)