Skip to content

File Formats

Jump to bottom
Dragon edited this page Dec 23, 2025 · 3 revisions

NaviDuck File Formats

Last updated: 12/22/2025

Overview

NaviDuck utilizes structured file formats for persistent storage of configuration, user data, and application state. All files are stored in JSON format with UTF-8 encoding to ensure cross-platform compatibility and human readability.

Configuration File (~/.naviduck_config.json)

Purpose

Stores user preferences and application settings that persist between sessions.

Location

  • Linux/macOS: ~/.naviduck_config.json
  • Windows: C:\Users\<username>\.naviduck_config.json

Schema

{
  "version": "3.0.0",
  "default_engine": "brave",
  "use_emoji": false,
  "engines": {
    "ddg": true,
    "ddg_api": true,
    "google": true,
    "wikipedia": true,
    "brave": true
  },
  "display": {
    "max_results": 10,
    "show_icons": true,
    "color_scheme": "default"
  },
  "network": {
    "timeout": 30,
    "max_retries": 3,
    "use_system_proxy": false
  }
}

Fields Description

Field Type Default Description
version string "3.0.0" Configuration file version
default_engine string "brave" Primary search engine identifier
use_emoji boolean false Display emoji instead of Nerd Font icons
engines object all true Enabled/disabled status per search engine
display.max_results integer 10 Maximum results to display per search
display.show_icons boolean true Show icons in interface
display.color_scheme string "default" Color theme identifier
network.timeout integer 30 Request timeout in seconds
network.max_retries integer 3 Maximum retry attempts
network.use_system_proxy boolean false Use system proxy settings

Notes

  • Configuration is loaded at application startup and saved on clean exit
  • Changes take effect immediately for most settings
  • Missing fields revert to defaults
  • File is created with defaults if missing

Data File (~/.naviduck_data.json)

Purpose

Stores user-generated content: browsing history, bookmarks, and session data.

Location

  • Linux/macOS: ~/.naviduck_data.json
  • Windows: C:\Users\<username>\.naviduck_data.json

Schema

{
  "history": [
    {
      "type": "search",
      "query": "python tutorial",
      "engine": "brave",
      "timestamp": "2025-12-22T14:30:45.123456",
      "results": 8
    },
    {
      "type": "visit",
      "url": "https://example.com",
      "title": "Example Domain",
      "timestamp": "2025-12-22T14:35:22.987654",
      "tor": false
    }
  ],
  "bookmarks": [
    {
      "title": "Python Documentation",
      "url": "https://docs.python.org",
      "added": "2025-12-20T09:15:30.000000",
      "tags": ["programming", "documentation"]
    }
  ],
  "cache": {
    "last_search": "python tutorial",
    "last_results": [
      {
        "title": "Python Tutorial",
        "url": "https://python.org/tutorial",
        "snippet": "Official Python tutorial...",
        "engine": "brave"
      }
    ]
  }
}

Fields Description

History Entries

Field Type Required Description
type string yes "search" or "visit"
query string conditional Search query (for type="search")
engine string conditional Search engine (for type="search")
url string conditional URL visited (for type="visit")
title string conditional Page title (for type="visit")
timestamp string yes ISO 8601 format with microseconds
results integer optional Number of results found
tor boolean optional Whether Tor was used

Bookmarks

Field Type Required Description
title string yes Bookmark title (max 80 chars)
url string yes Full URL
added string yes ISO 8601 timestamp
tags array optional User-defined tags

Cache

Field Type Description
last_search string Most recent search query
last_results array Cached search results

Data Management

  • History is limited to 100 most recent entries (FIFO)
  • Bookmarks have no practical limit
  • Cache is temporary and may be cleared
  • Data is saved incrementally during operation

Tor Data Directory

Purpose

Temporary storage for Tor process data when using built-in Tor functionality.

Location

Temporary directory with prefix naviduck_tor_ (OS-specific):

  • Linux/macOS: /tmp/naviduck_tor_XXXXXX
  • Windows: C:\Users\<username>\AppData\Local\Temp\naviduck_tor_XXXXXX

Contents

  • Tor configuration files
  • Identity data
  • Log files (if enabled)
  • Cache data

Notes

  • Created when Tor starts via tor start command
  • Automatically cleaned up on Tor stop or application exit
  • Contains no persistent user data
  • May contain identifiable network information

File Operations

Creation

Files are created automatically when needed:

  1. Check if file exists at standard location
  2. Create with default schema if missing
  3. Set appropriate file permissions (600 on Unix-like systems)
  4. Write initial data

Reading

def load_config():
    try:
        with open(config_path, 'r', encoding='utf-8') as f:
            return json.load(f)
    except FileNotFoundError:
        return create_default_config()
    except json.JSONDecodeError:
        return handle_corrupted_config()

Writing

def save_config(config):
    try:
        # Create backup of existing file
        if os.path.exists(config_path):
            shutil.copy2(config_path, config_path + '.backup')
        
        # Write new configuration
        with open(config_path, 'w', encoding='utf-8') as f:
            json.dump(config, f, indent=2, ensure_ascii=False)
        
        # Set secure permissions
        os.chmod(config_path, 0o600)
        
    except Exception as e:
        logger.error(f"Failed to save config: {e}")
        # Attempt to restore from backup

Validation

All files are validated on load:

  1. JSON syntax validation
  2. Schema validation (required fields, types)
  3. Value range checking
  4. Security checks (no executable content)

Security Considerations

File Permissions

  • Configuration and data files: 600 (owner read/write only)
  • Temporary files: Default system temporary permissions
  • Backup files: Same as original files

Data Protection

  • No encryption at rest (plain JSON)
  • Sensitive data minimization
  • No passwords or API keys stored
  • Tor identity data in temporary directories only

Integrity

  • JSON format prevents binary corruption
  • Schema validation on load
  • Automatic backup before overwrites
  • Fallback to defaults on corruption

Migration and Compatibility

Versioning

Each configuration file includes a version field to handle schema changes.

Migration Path

  1. Detect version mismatch
  2. Apply migration transforms if available
  3. Update version field
  4. Save migrated configuration

Backward Compatibility

  • New fields added with defaults
  • Obsolete fields ignored but preserved
  • Major version changes may require manual intervention
  • Migration scripts provided for significant changes

Troubleshooting

Common Issues

Issue Symptoms Resolution
Corrupted JSON Application fails to start Delete file (will be recreated) or restore backup
Permission denied Cannot save settings Check file ownership and permissions (should be 600)
Invalid schema Settings not loading Check version compatibility or reset to defaults
Disk full Save operations fail Free disk space or change storage location

Recovery Options

  1. Automatic: Delete corrupted file → fresh start with defaults
  2. Manual: Edit JSON file with text editor
  3. Backup: Restore from *.backup file
  4. Reset: Use naviduck --reset-config (if implemented)

Debugging

Enable verbose logging to see file operations:

NAVIDUCK_DEBUG=1 python naviduck.py

Best Practices

For Users

  • Backup configuration before major updates
  • Version control configuration if customizing extensively
  • Report corrupted files as bugs
  • Use secure locations for sensitive data

For Developers

  • Always validate before use
  • Provide migration paths
  • Maintain backward compatibility when possible
  • Document schema changes
  • Handle errors gracefully

For System Administrators

  • Monitor disk usage for Tor temporary files
  • Set appropriate ulimits for file descriptors
  • Consider location for multi-user systems
  • Audit configuration for security compliance

Future Considerations

Planned Enhancements

  1. Optional encryption for sensitive data
  2. Cloud synchronization support
  3. Import/export functionality
  4. Configuration profiles
  5. Advanced backup strategies

Deprecation Schedule

No current deprecations. Schema changes will be announced with:

  • 6 months notice for breaking changes
  • Migration tools provided
  • Dual support during transition periods

Related Documentation

Last updated: 12/23/2025
File Formats version: 3.0.0

Clone this wiki locally