elpatron/octo-funnel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Activity
Files
87f0792eb7b29de1cdb296d597d763626d6f2d29
octo-funnel/.qoder/quests/octoprint-tailscale-plugin.md

7.3 KiB
Raw Blame History

OctoPrint Tailscale Funnel Plugin Design Document

1. Overview

The OctoPrint Tailscale Funnel Plugin is designed to make the OctoPrint web interface publicly accessible via Tailscale Funnel. This plugin will enable users to securely access their OctoPrint instance from anywhere on the internet without needing to configure port forwarding, dynamic DNS, or deal with complex firewall settings.

1.1 Purpose

The primary purpose of this plugin is to provide a simple, secure way for OctoPrint users to access their 3D printer's web interface remotely using Tailscale's Funnel feature, which creates encrypted tunnels from the public internet to local services.

1.2 Scope

This plugin will:

  • Integrate with the existing Tailscale installation on the system
  • Provide a user interface within OctoPrint to enable/disable Funnel access
  • Configure and manage Tailscale Funnel for the OctoPrint web service
  • Display the public URL for accessing OctoPrint remotely
  • Handle authentication and security considerations

2. Architecture

2.1 System Components

The plugin consists of the following components:

  1. Plugin Core: The main plugin implementation that integrates with OctoPrint's plugin system
  2. Tailscale Interface: Component that communicates with the Tailscale daemon via CLI
  3. Web UI: Frontend elements that allow users to configure and monitor Funnel status
  4. Settings Management: Component that stores and retrieves plugin configuration
  5. Status Monitor: Background service that monitors the Funnel connection status

2.2 Component Interaction Diagram

graph TD
    A[OctoPrint Web Interface] --> B[Plugin Core]
    B --> C[Tailscale Interface]
    B --> D[Web UI]
    B --> E[Settings Management]
    B --> F[Status Monitor]
    C --> G[Tailscale Daemon]
    D --> A
    E --> B
    F --> C

2.3 Plugin Integration Points

The plugin will integrate with OctoPrint through several mixin types:

  • StartupPlugin: Initialize Tailscale integration on startup
  • SettingsPlugin: Manage plugin configuration
  • AssetPlugin: Provide custom JavaScript and CSS assets
  • TemplatePlugin: Add UI elements to OctoPrint's interface
  • BlueprintPlugin: Create custom API endpoints for plugin functionality

3. Plugin Features

3.1 Core Functionality

Feature Description
Funnel Enable/Disable Toggle Tailscale Funnel for OctoPrint web interface
Status Monitoring Display current Funnel connection status
Public URL Display Show the public URL for accessing OctoPrint
Configuration Management Store and retrieve plugin settings

3.2 User Interface

The plugin will add a new section to OctoPrint's settings panel with the following elements:

  1. Status Indicator: Shows whether Funnel is currently enabled or disabled
  2. Enable/Disable Button: Toggle to turn Funnel on or off
  3. Public URL Display: Shows the public URL when Funnel is enabled
  4. Status Messages: Displays current status and any error messages

3.3 Security Considerations

  1. The plugin will require explicit user consent before enabling Funnel
  2. All communication with Tailscale will be done through the local CLI
  3. The plugin will not store any authentication credentials
  4. Users will be warned about the security implications of making their printer accessible from the internet

4. Implementation Details

4.1 Plugin Structure

The plugin will follow a standard OctoPrint plugin structure with separate directories for Python code, static assets (JavaScript and CSS), templates, and documentation files.

4.2 Main Plugin Implementation

The main plugin class will implement several OctoPrint mixins:

  • StartupPlugin: Initialize Tailscale integration on startup
  • SettingsPlugin: Manage plugin configuration
  • AssetPlugin: Provide custom JavaScript and CSS assets
  • TemplatePlugin: Add UI elements to OctoPrint's interface
  • BlueprintPlugin: Create custom API endpoints for plugin functionality

4.3 Tailscale Integration

The plugin will interact with Tailscale through subprocess calls to the Tailscale command-line tool to check status, enable/disable Funnel, and retrieve connection information.

4.4 Configuration Options

The plugin will store the following settings:

Setting Description Default
enabled Whether Funnel is enabled False
port Port to expose via Funnel 80
confirm_enable Require confirmation before enabling True

5. API Endpoints

5.1 Custom API Routes

The plugin will expose the following API endpoints:

Endpoint Method Description
/api/plugin/tailscale_funnel/status GET Get current Funnel status
/api/plugin/tailscale_funnel/enable POST Enable Tailscale Funnel
/api/plugin/tailscale_funnel/disable POST Disable Tailscale Funnel

5.2 API Response Format

All API responses will follow a standardized format that includes a status indicator, descriptive message, and data payload.

6. Frontend Implementation

6.1 JavaScript Components

The frontend will include a view model that:

  • Fetches current Funnel status from the backend
  • Provides methods to enable/disable Funnel
  • Updates the UI with status information
  • Handles user interactions

6.2 UI Elements

The settings panel will include:

  • Toggle switch for enabling/disabling Funnel
  • Read-only field displaying the public URL
  • Status indicator showing connection state
  • Action buttons for enabling/disabling
  • Warning messages about security implications

7. Error Handling

7.1 Common Error Conditions

Error Cause Handling
Tailscale not installed Missing tailscale command Show installation instructions
Not connected to tailnet Tailscale not logged in Prompt user to login
Insufficient permissions User can't run tailscale Show permission error
Funnel not enabled Admin setting Show configuration instructions

7.2 User Feedback

The plugin will provide clear feedback for all operations:

  • Success messages when operations complete
  • Error messages with troubleshooting suggestions
  • Progress indicators during operations
  • Status updates in real-time

8. Testing Strategy

8.1 Unit Tests

Unit tests will cover:

  • Tailscale command execution
  • Status parsing logic
  • Configuration management
  • API endpoint responses

8.2 Integration Tests

Integration tests will verify:

  • Proper communication with Tailscale daemon
  • Correct UI updates based on status changes
  • Settings persistence
  • Error handling scenarios

8.3 Manual Testing

Manual testing will validate:

  • UI appearance and usability
  • End-to-end enable/disable workflow
  • Error message clarity
  • Cross-platform compatibility

9. Deployment

9.1 Installation Requirements

  • OctoPrint 1.3.0 or higher
  • Tailscale installed and configured on the system
  • Python 3.7 or higher

9.2 Installation Process

  1. Install Tailscale on the system
  2. Install the plugin through OctoPrint's plugin manager
  3. Configure plugin settings in OctoPrint's settings panel
  4. Enable Funnel through the plugin interface

9.3 Dependencies

The plugin will have minimal dependencies:

  • Standard Python libraries for subprocess management
  • OctoPrint's built-in plugin framework
  • Tailscale CLI (installed separately by user)