{"id":35492858,"url":"https://github.com/network-plane/shareplane","last_synced_at":"2026-01-13T23:32:36.765Z","repository":{"id":230647793,"uuid":"779893302","full_name":"network-plane/shareplane","owner":"network-plane","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-04T13:17:16.000Z","size":102,"stargazers_count":0,"open_issues_count":34,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-13T19:42:45.611Z","etag":null,"topics":["cli","file","file-sharing","server","sharing"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/network-plane.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security.go","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-03-31T04:27:57.000Z","updated_at":"2026-01-04T13:17:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"b5e1796d-4901-48bd-b1d7-ae6d2b0b54a2","html_url":"https://github.com/network-plane/shareplane","commit_stats":null,"previous_names":["earentir/shs"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/network-plane/shareplane","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/network-plane%2Fshareplane","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/network-plane%2Fshareplane/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/network-plane%2Fshareplane/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/network-plane%2Fshareplane/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/network-plane","download_url":"https://codeload.github.com/network-plane/shareplane/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/network-plane%2Fshareplane/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28405302,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T21:51:37.118Z","status":"ssl_error","status_checked_at":"2026-01-13T21:45:14.585Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","file","file-sharing","server","sharing"],"created_at":"2026-01-03T16:14:32.862Z","updated_at":"2026-01-13T23:32:36.758Z","avatar_url":"https://github.com/network-plane.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# shareplane - Simple HTTP Server\n\nA lightweight HTTP server written in Go for serving files and directories over HTTP. Perfect for quick file sharing.\n\n## Features\n\n- **Simple \u0026 Fast**: Minimal overhead, easy to use\n- **File \u0026 Directory Serving**: Serve individual files or entire directories\n- **HTTP Range Support**: Supports HTTP Range requests (206 Partial Content) for resuming downloads and partial file fetches\n- **Download Statistics**: Track downloads with byte counts and request statistics\n- **Customizable Binding**: Configure IP address and port\n- **Network Interface Detection**: When binding to `0.0.0.0`, automatically shows all available IP addresses\n- **File Listing**: Automatic HTML file listing at the root path\n- **Glob Pattern Support**: Use glob patterns to select multiple files\n- **Hidden File Filtering**: Hidden files (starting with `.`) are excluded from listings by default\n- **File Hashing**: Optional SHA1 hash calculation and display for files in listings\n- **Customizable Colors**: Customize the color scheme of the file listing interface\n- **Bandwidth Limiting**: Optional bandwidth throttling for file transfers\n- **Rate Limiting**: Built-in DoS protection with per-IP request rate limiting (default: 20 req/s)\n- **Idle Timeout**: Automatically shut down the server after a period of inactivity\n- **Real-time Progress**: See download progress as files are served\n- **Graceful Shutdown**: Print statistics on exit (SIGINT/SIGTERM)\n\n## Installation\n\n### Build from Source\n\n```bash\ngo build -o shareplane\n```\n\n## Usage\n\n### Basic Usage\n\nServe a single file:\n```bash\n./shareplane file.txt\n```\n\nServe multiple files:\n```bash\n./shareplane file1.txt file2.txt file3.txt\n```\n\nServe a directory:\n```bash\n./shareplane /path/to/directory\n```\n\nServe multiple files and directories:\n```bash\n./shareplane file.txt /path/to/dir1 /path/to/dir2\n```\n\n### Command-Line Options\n\n- `--port`: Port to listen on (default: `8080`)\n  ```bash\n  ./shareplane --port 3000 file.txt\n  ```\n\n- `--ip`: IP address to bind to (default: `0.0.0.0` - all interfaces)\n  ```bash\n  ./shareplane --ip 127.0.0.1 file.txt\n  ```\n  When binding to `0.0.0.0`, the server will display all available network interfaces and their IP addresses.\n\n- `--show-hidden`: Show files and directories starting with a dot (`.`) in file listings (hidden files are hidden by default)\n  ```bash\n  ./shareplane --show-hidden /path/to/directory\n  ```\n\n- `--hash`: Calculate and display SHA1 hash for files in the listing\n  ```bash\n  ./shareplane --hash /path/to/directory\n  ```\n\n- `--max-hash-size`: Maximum file size (in bytes) to calculate hash for (0 = no limit, default: 0)\n  ```bash\n  ./shareplane --hash --max-hash-size 10485760 /path/to/directory  # Only hash files up to 10MB\n  ```\n\n- `--bw-limit`: Bandwidth limit for file transfers (e.g., `5MB`, `250KB`, `5M`, `1.4G`, or plain bytes). No limit if not specified.\n  ```bash\n  ./shareplane --bw-limit 5MB /path/to/directory  # Limit to 5MB/s\n  ./shareplane --bw-limit 1.4G /path/to/directory  # Limit to 1.4GB/s\n  ```\n\n- `--rate-limit`: Rate limit: maximum requests per second per IP address (default: 20, use 0 to disable). Helps protect against DoS attacks while allowing normal browsing.\n  ```bash\n  ./shareplane --rate-limit 30 /path/to/directory    # Allow 30 requests/second per IP\n  ./shareplane --rate-limit 0 /path/to/directory      # Disable rate limiting\n  ./shareplane /path/to/directory                     # Uses default: 20 requests/second per IP\n  ```\n\n- `--reload`: Enable auto-reload: monitor files for changes in real-time using file system notifications (new files, removed files, modified files)\n  ```bash\n  ./shareplane --reload /path/to/directory\n  ```\n\n- `--idle`: Idle timeout: server shuts down after this period of inactivity. Default: 15m if flag is set without value. Supports units: M (minutes), H (hours), D (days), W (weeks), Mo (months). Examples: `15m`, `1H`, `4D`, `1W`, `1Mo`\n  ```bash\n  ./shareplane --idle file.txt                    # Default: 15 minutes\n  ./shareplane --idle 30m /path/to/directory     # 30 minutes\n  ./shareplane --idle 2H /path/to/directory      # 2 hours\n  ./shareplane --idle 1D /path/to/directory       # 1 day\n  ./shareplane --idle 1W /path/to/directory       # 1 week\n  ```\n\n- `--colours`: Customize the color scheme of the file listing interface. Requires 7 comma-separated colors in this order:\n  1. Background (body background)\n  2. Text (heading text)\n  3. Table header Background\n  4. Table header text\n  5. Table Background\n  6. Table filename text (link color)\n  7. Table other text\n  ```bash\n  ./shareplane --colours \"#000000,#FFFFFF,#FF0000,#FFFFFF,#CCCCCC,#0000FF,#333333\" /path/to/directory\n  ```\n  Colors can be specified as hex codes (with or without `#`) or named CSS colors (e.g., `red`, `blue`, `white`).\n\n- Environment Variables:\n  - `PORT`: Set the port (same as `--port`)\n  - `IP`: Set the IP address (same as `--ip`)\n\n### Examples\n\nServe files on a custom port:\n```bash\n./shareplane --port 9000 document.pdf image.jpg\n```\n\nServe only on localhost:\n```bash\n./shareplane --ip 127.0.0.1 --port 8080 /path/to/files\n```\n\nUse glob patterns:\n```bash\n./shareplane *.txt *.pdf\n```\n\nShow hidden files in listings (hidden files are hidden by default):\n```bash\n./shareplane --show-hidden /path/to/directory\n```\n\nShow SHA1 hashes for files:\n```bash\n./shareplane --hash /path/to/directory\n```\n\nShow SHA1 hashes with size limit (only hash files up to 100MB):\n```bash\n./shareplane --hash --max-hash-size 104857600 /path/to/directory\n```\n\nLimit bandwidth to 5MB/s:\n```bash\n./shareplane --bw-limit 5MB /path/to/directory\n```\n\nCustomize colors with a dark theme:\n```bash\n./shareplane --colours \"#1a1a1a,#e0e0e0,#2d2d2d,#ffffff,#252525,#4a9eff,#cccccc\" /path/to/directory\n```\n\nCustomize colors with a light blue theme:\n```bash\n./shareplane --colours \"#f0f8ff,#1a1a1a,#4a90e2,#ffffff,#ffffff,#0066cc,#333333\" /path/to/directory\n```\n\nCustomize colors using named colors:\n```bash\n./shareplane --colours \"black,white,red,white,gray,blue,darkgray\" /path/to/directory\n```\n\nAccess files:\n- Visit `http://localhost:8080/` to see a file listing\n- Access files directly: `http://localhost:8080/filename.txt`\n\n## API Endpoint\n\nThe server provides a JSON API endpoint for programmatic access to file listings. This is useful for scripts, tools, and automation.\n\n### `/api/files`\n\nReturns a JSON response with file listings, totals, and metadata.\n\n**Query Parameters:**\n- `path` (optional): Directory path to list. If not provided, lists all shared files/directories.\n\n**Response Format:**\n```json\n{\n  \"files\": [\n    {\n      \"name\": \"/full/path/to/file.txt\",\n      \"displayName\": \"file.txt\",\n      \"size\": 1024,\n      \"modTime\": \"2024-01-01T12:00:00Z\",\n      \"hash\": \"abc123...\",\n      \"isDir\": false\n    }\n  ],\n  \"totalSize\": 1048576,\n  \"fileCount\": 10,\n  \"showHash\": true\n}\n```\n\n**Response Fields:**\n- `files`: Array of file/directory objects\n  - `name`: Full absolute path (internal use)\n  - `displayName`: Relative path for display\n  - `size`: File size in bytes\n  - `modTime`: Modification time (ISO 8601 format)\n  - `hash`: SHA1 hash (empty if not calculated or disabled)\n  - `isDir`: Boolean indicating if this is a directory\n- `totalSize`: Total size of all files in bytes (directories excluded)\n- `fileCount`: Total number of files (directories excluded)\n- `showHash`: Boolean indicating if hash calculation is enabled\n\n### API Usage Examples\n\n**List all shared files (root):**\n```bash\ncurl http://localhost:8080/api/files\n```\n\n**List files in a specific directory:**\n```bash\ncurl \"http://localhost:8080/api/files?path=subdirectory\"\n```\n\n**Pretty-print JSON response:**\n```bash\ncurl http://localhost:8080/api/files | jq\n```\n\n**List files and extract only file names:**\n```bash\ncurl -s http://localhost:8080/api/files | jq -r '.files[] | select(.isDir == false) | .displayName'\n```\n\n**Get total size of all files:**\n```bash\ncurl -s http://localhost:8080/api/files | jq '.totalSize'\n```\n\n**List files with their sizes (formatted):**\n```bash\ncurl -s http://localhost:8080/api/files | jq -r '.files[] | \"\\(.displayName): \\(.size) bytes\"'\n```\n\n**Download a file using curl:**\n```bash\ncurl -O http://localhost:8080/filename.txt\n```\n\n**Download with progress bar:**\n```bash\ncurl -# -O http://localhost:8080/largefile.zip\n```\n\n**Resume a partial download:**\n```bash\ncurl -C - -O http://localhost:8080/largefile.zip\n```\n\n**Check if a file exists (HEAD request):**\n```bash\ncurl -I http://localhost:8080/filename.txt\n```\n\n**Get file metadata without downloading:**\n```bash\ncurl -I http://localhost:8080/filename.txt\n```\n\n**List files in a nested directory:**\n```bash\ncurl \"http://localhost:8080/api/files?path=docs/subdir\"\n```\n\n**Filter directories only:**\n```bash\ncurl -s http://localhost:8080/api/files | jq '.files[] | select(.isDir == true) | .displayName'\n```\n\n**Get files with hashes (when --hash is enabled):**\n```bash\ncurl -s http://localhost:8080/api/files | jq '.files[] | select(.hash != \"\") | {name: .displayName, hash: .hash}'\n```\n\n**Save API response to file:**\n```bash\ncurl -s http://localhost:8080/api/files -o file_listing.json\n```\n\n**Use API in a script (bash example):**\n```bash\n#!/bin/bash\nAPI_URL=\"http://localhost:8080/api/files\"\nFILES=$(curl -s \"$API_URL\" | jq -r '.files[] | select(.isDir == false) | .displayName')\n\nfor file in $FILES; do\n    echo \"Processing: $file\"\n    # Your processing logic here\ndone\n```\n\nWhen binding to `0.0.0.0`, the server will show output like:\n```bash\nServing on http://0.0.0.0:8080\nAvailable on:\n  http://192.168.1.100:8080\n  http://10.0.0.5:8080\n  http://127.0.0.1:8080\n  http://localhost:8080\n```\n\n## HTTP Range Requests\n\nThe server fully supports HTTP Range requests (RFC 7233), which enables:\n- **Resuming Downloads**: Clients can resume interrupted downloads by requesting specific byte ranges\n- **Partial Fetches**: Clients can request specific portions of files (e.g., for video streaming or large file processing)\n- **Efficient Transfers**: Reduces bandwidth usage when only part of a file is needed\n\nThe server automatically handles `Range` headers and responds with `206 Partial Content` when appropriate. This is transparent to users - any HTTP client that supports Range requests will automatically benefit from this feature.\n\n## Proxy Support\n\nWhen running behind a reverse proxy (such as frps, nginx, or Cloudflare), the server automatically detects and uses the real client IP address from proxy headers. The server checks the following headers in order:\n\n1. `X-Forwarded-For` - Most common header, contains the original client IP\n2. `X-Real-IP` - Common in nginx and other proxies\n3. `X-Forwarded` - Alternative format for forwarded IPs\n4. `CF-Connecting-IP` - Cloudflare-specific header\n\nIf no proxy headers are present, the server falls back to the connection's `RemoteAddr`. The real client IP is displayed in the download logs, making it easy to track which clients are downloading files even when behind a proxy.\n\n## Statistics\n\nThe server tracks download statistics for each file:\n- Number of times each file was downloaded\n- Total bytes sent for each file\n- Total bytes sent for file listings\n\nStatistics are printed when the server is terminated (Ctrl+C or SIGTERM).\n\n## License\n\nSee [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetwork-plane%2Fshareplane","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetwork-plane%2Fshareplane","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetwork-plane%2Fshareplane/lists"}