david/myworkspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: LinkSyncServer and LinkSyncExtension projects with complete documentation, models, API endpoints, tests, and extension implementation

Browse Source
This commit is contained in:
DavidSaylor
2026-05-11 17:37:10 -05:00
parent ad0b12b452
commit aed69afdfd
691 changed files with 181874 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

308
Linkding Browser Extension/LinkdingSync/docs/phase0-plan.md Normal file
View File

@@ -0,0 +1,308 @@
# Phase 0: Testing & Server Behavior Validation
## Overview
This document outlines the complete Phase 0 plan for testing Linkding server behavior before redesigning the LinkdingSync extension. The goal is to gather critical information about:
1. **API Key Isolation**: Do API keys provide bookmark isolation, or is the user account the only isolation boundary?
2. **Conflict Resolution**: How does Linkding handle same URL in different contexts (paths, notes)?
3. **Delete Behavior**: Does deletion via one API key affect bookmarks created by other keys?
4. **Bundle Tag Filtering**: How do bundles act as filters for bookmark queries?
## Current Status
| Item | Status |
|------|--------|
| Review extension codebase | ✅ Complete |
| Review Linkding source code | ✅ Complete |
| Analyze TODOs.txt findings | ✅ Complete |
| Create test scenarios doc | ✅ Complete |
| Create test runner script | ✅ Complete |
| **Execute tests** | ⏳ Pending |
| **Finalize design** | ⏳ Pending |
---
## Prerequisites
### 1. Create Test User Accounts
You need to create **2 user accounts** on your Linkding instance:
```
user_work - For work-related bookmarks
user_personal - For personal bookmarks
```
### 2. Create API Keys
For each user, create **at least 2 API keys** (one per bundle):
| User | Key Purpose | Example Name |
|------|-------------|--------------|
| user_work | Work bundle access | `user_work_key_1` |
| user_work | Work bundle access | `user_work_key_2` |
| user_personal | Personal bundle access | `user_personal_key_1` |
| user_personal | Personal bundle access | `user_personal_key_2` |
**How to create API keys**:
1. Go to Linkding settings → Advanced
2. Click "Create new token"
3. Give it a descriptive name (e.g., "work-bundle-1")
4. Copy the generated key (it won't be shown again)
### 3. Create Bundles
Create bundles for filtering:
| Bundle Name | Purpose |
|-------------|---------|
| `work` | Filter work bookmarks |
| `personal` | Filter personal bookmarks |
### 4. Firefox Configuration
#### Option A: Single Firefox Profile with Multiple API Keys
Create a Firefox profile that can hold multiple API keys for testing. This allows:
- Easy switching between work/personal contexts
- Running automated tests via DevTools console
#### Option B: Separate Firefox Profiles
Create two separate Firefox profiles:
- `work-profile` - Configured with work API key
- `personal-profile` - Configured with personal API key
This is simpler but requires switching profiles between tests.
---
## Test Execution Instructions
### Step 1: Load Test Runner
1. Open Firefox
2. Navigate to your Linkding settings page (any page works)
3. Open DevTools (press `F12`)
4. Go to the **Console** tab
5. Copy the entire contents of `test-runner.js`
6. Paste into the console (Ctrl+Shift+V)
7. Press Enter
You should see:
```
LinkdingSync Test Runner loaded successfully
```
### Step 2: Configure Credentials
In the console, modify the `CONFIG` object:
```javascript
const CONFIG = {
serverUrl: 'https://links.blabber1565.com',
workApiKey: 'your_work_api_key_here', // Paste API key
personalApiKey: 'your_personal_api_key_here',
workUser: 'user_work',
personalUser: 'user_personal',
workBundle: 'work',
personalBundle: 'personal',
cleanupAfterTests: true
};
```
**Security Note**:
- API keys are stored in the Firefox session (cleared when Firefox closes)
- Consider creating a separate `.creds.txt` file for manual reference if needed
### Step 3: Run Tests
Execute the test suite:
```javascript
runTestSuite()
```
This will run all 6 test scenarios and display results in the console.
### Step 4: Analyze Results
Each test will output:
- Setup information
- API responses
- **Result analysis** with ✓ or ✗ indicators
Example output:
```
=== Scenario 1: Same URL, Different API Keys, Same User ===
✓ Created: ID=123, URL=https://example.com
✓ Created: ID=456, URL=https://example.com
Results:
Bookmark 1 ID: 123
Bookmark 2 ID: 456
✅ RESULT: Different bookmark IDs - API keys provide isolation
```
### Step 5: Cleanup (Optional)
After tests complete, clean up test bookmarks:
```javascript
cleanup()
```
Or disable automatic cleanup in CONFIG:
```javascript
cleanupAfterTests: false
```
---
## Expected Test Outcomes
### Test 1: API Key Isolation
**Possible Results:**
- **Same ID**: API keys don't provide isolation - user account is the only boundary
- **Different IDs**: API keys provide isolation within same user
**Decision Impact**:
- If keys don't isolate → Use separate users for work/personal isolation
- If keys do isolate → Can use same user with different API keys
### Test 2: Cross-User Visibility
**Possible Results:**
- **User B sees User A's bookmarks**: Sharing enabled or same underlying user
- **User B cannot see User A's bookmarks**: Proper isolation
**Decision Impact**:
- Need separate users with sharing disabled for true isolation
### Test 3: Path Conflict Resolution
**Possible Results:**
- **Same ID**: Server merges by URL, last-write-wins for path/notes
- **Different IDs**: Server creates separate bookmarks
**Decision Impact**:
- If merges → Need path merge strategy (keep both, prompt user, etc.)
- If separate → Can use duplicate bookmarks for different contexts
### Test 4: Title/Description Merge
**Possible Results:**
- **Last-write-wins**: Most recent update wins
- **Merge**: Both values combined somehow
- **No conflict**: Different titles preserved
**Decision Impact**:
- Determine merge strategy for conflict resolution
### Test 5: Delete Propagation
**Possible Results:**
- **Propagates**: Deleting via one key deletes all
- **Doesn't propagate**: Separate bookmarks per key
**Decision Impact:**
- Aligns with Test 3 results
### Test 6: Bundle Tag Filtering
**Possible Results:**
- **Works**: Tags filter bookmarks by tag
- **Doesn't work**: Tags don't provide isolation
**Decision Impact:**
- Bundle tags can provide logical separation
---
## Test Results Analysis Template
After running tests, document results in `docs/test-results.md`:
```markdown
# Test Results
## Test 1: API Key Isolation
- **Result**: [same/different] IDs
- **Conclusion**: API keys [do/don't] provide isolation
- **Implication**: Need [separate users OR same user strategy]
## Test 2: Cross-User Visibility
- **Result**: User B [can/cannot] see User A's bookmarks
- **Conclusion**: Sharing is [enabled/disabled]
- **Implication**: [Use different users or different settings]
## Test 3: Path Conflict Resolution
- **Result**: [same/different] IDs
- **Conclusion**: Server [merges/creates separate] bookmarks
- **Implication**: [Merge paths OR keep separate]
## Test 4: Title/Description Conflict
- **Result**: [last-write-wins/merge/no-conflict]
- **Conclusion**: Server [uses last-write/merges/doesn't conflict]
- **Implication**: [Strategy for conflict resolution]
## Test 5: Delete Propagation
- **Result**: Delete [propagated/didn't propagate]
- **Conclusion**: Deletion [affects all OR affects specific]
- **Implication**: [Delete strategy]
## Test 6: Bundle Tag Filtering
- **Result**: Bundle tags [work/don't work]
- **Conclusion**: Tags [provide/isolate] bookmarks
- **Implication**: [Use tags OR use users]
## Final Strategy
Based on results:
- [User isolation approach]
- [Conflict resolution strategy]
- [Sync behavior]
```
---
## Next Steps After Phase 0
Once tests complete:
1. **Analyze Results**: Review test outputs and document in `test-results.md`
2. **Finalize Design**: Create new `design.md` with confirmed behaviors
3. **Redesign Extension**: Implement new architecture based on test findings
4. **Create Tests**: Write unit tests in `tests/` directory
5. **Implement Features**: Add UI improvements and scheduled sync
6. **Document**: Update README.md and API docs
---
## Files Created
| File | Purpose |
|------|---------|
| `docs/phase0-test-scenarios.md` | Detailed test scenarios |
| `test-runner.js` | Automated test execution script |
| `docs/phase0-plan.md` | This document |
---
## Questions for You
Before you create the test accounts and run tests:
1. **Firefox Setup**: Which option do you prefer?
- Single profile with multiple API keys (more complex, more flexible)
- Separate profiles (simpler, less flexible)
2. **API Key Count**: Do you want to create:
- 2 API keys per user (minimal for testing)
- 4 API keys per user (more scenarios)
3. **Bundles**: Should we create:
- 2 bundles (`work`, `personal`)
- 4 bundles (more granular)
4. **Test Execution**: Will you run:
- All tests at once (`runTestSuite()`)
- Individual tests as you discover issues
Let me know, and I can adjust the test runner accordingly. Once you're ready to create the test accounts, just let me know and I'll provide final instructions.