# Go File & Directory I/O HTTP Server

A lightweight cross-platform HTTP server written in Go providing file and directory I/O operations (such as `/ls`, `/rm`, `/mv`, `/mkdir`, `/cat`, `/write`, `/stat`, `/pwd`) with support for Linux and Windows 10/11.

It supports **Byte-Range** (RFC 7233 & query params), **Line-Range** (streaming line slicing & replacement), and **Binary file transfers / chunked patching** to avoid unnecessary memory overhead and high network transfer costs for large files.

---

## 🚀 Quick Start

### Build & Run
```bash
# Run directly
go run main.go -addr :8080

# Build Linux binary
go build -o ioserver main.go

# Build Windows 10/11 executable
GOOS=windows GOARCH=amd64 go build -o ioserver.exe main.go
```

### Command-Line Options
```bash
Usage of ./ioserver:
  -addr string
        HTTP server listen address (default ":8080")
  -root string
        Optional root directory constraint / jail (default allows full filesystem)
  -cors
        Enable Cross-Origin Resource Sharing (CORS) (default true)
  -verbose
        Log request details to terminal (default true)
```

---

## 📡 API Endpoints

### 1. Read File Content (`/cat` or `/read`)
Streams file contents. Supports **full file**, **byte ranges**, **line ranges**, and **binary downloads**.

- **URL:** `/cat` or `/read`
- **Method:** `GET`
- **Parameters:**
  - `path`: File path to read
  - **Byte-Range Parameters:**
    - `bytes`: Byte slice range (e.g. `0-1023`, `500-`, `-100` for last 100 bytes)
    - `offset` & `length` (or `limit`): Byte offset and count (e.g. `offset=1024&length=512`)
    - HTTP Header: `Range: bytes=0-499` (returns `206 Partial Content` with `Content-Range`)
  - **Line-Range Parameters:**
    - `lines`: Line slice range (1-indexed, e.g. `1-50`, `100-`, `-20` for last 20 lines, `42` for single line)
    - `start_line` & `end_line`: Alternative line range syntax
    - `tail`: Read last N lines (e.g. `tail=100`)
    - `numbered`: Set `true` to prefix lines with line numbers (`1: ...`)
  - **Binary Option:**
    - `binary` / `download`: Set `true` to force `application/octet-stream` and `Content-Disposition: attachment`

#### Examples:
```bash
# Read byte range: first 1KB of a large binary file
curl "http://localhost:8080/cat?path=data.bin&bytes=0-1023"

# Read byte range via standard HTTP Range header (RFC 7233)
curl -H "Range: bytes=1048576-2097151" "http://localhost:8080/cat?path=large_video.mp4"

# Read line range: lines 100 to 200 with line numbers
curl "http://localhost:8080/cat?path=app.log&lines=100-200&numbered=true"

# Read the last 50 lines (tail) of a log file
curl "http://localhost:8080/cat?path=access.log&tail=50"

# Read single line
curl "http://localhost:8080/cat?path=config.env&line=5"
```

---

### 2. Write / Patch File (`/write`)
Writes, appends, or patches files. Supports **binary streams**, **byte-offset patching**, and **line-range replacement**.

- **URL:** `/write`
- **Method:** `POST` / `GET`
- **Parameters:**
  - `path`: Target file path
  - `content`: Content string (or send raw binary data in HTTP POST body)
  - `offset`: Byte offset to write at without rewriting the entire file
  - `lines` (or `start_line` & `end_line`): Replace a specific line range in a text file
  - `append`: `true` to append data to the end of the file

#### Examples:
```bash
# Full write (binary file)
curl -X POST "http://localhost:8080/write?path=image.png" --data-binary @image.png

# Patch a chunk at byte offset (e.g. at 1MB mark)
curl -X POST "http://localhost:8080/write?path=disk.img&offset=1048576" --data-binary @chunk.bin

# Replace lines 10 through 20 in a file
curl -X POST "http://localhost:8080/write?path=config.yaml&lines=10-20" --data "new_setting: true\n"

# Append text to log file
curl -X POST "http://localhost:8080/write?path=events.log&append=true" --data "New log entry\n"
```

---

### 3. List Files & Directories (`/ls`)
Lists entries in a directory or inspects a single file.

> **Windows 10/11 Root Drive Discovery**: When querying root (`path=/` or `path=\` or `path=drives` or `path=root`) on Windows, `/ls` queries the Win32 `GetLogicalDrives` API and returns all available mounted drive letters (`c:/`, `d:/`, `e:/`, etc.).

- **URL:** `/ls`
- **Method:** `GET` / `POST`
- **Parameters:**
  - `path`: Target file or directory path (e.g. `c:/dir1/`, `/tmp`, `/`, `./sub`). Defaults to `.`.
  - `args`: Flags (`-a`, `-l`, `-h`, `-alh`, `-t`, `-S`, `-r`)
  - `format`: `text` (default formatted table) or `json`

**Examples:**
```bash
# List available drives on Windows 10/11 (returns c:/, d:/, e:/)
curl "http://localhost:8080/ls?path=/"
curl "http://localhost:8080/ls?path=/&args=-alh"

# Windows directory listing with -alh flags
curl "http://localhost:8080/ls?args=-alh&path=c:/dir1/"

# Linux path with JSON output
curl "http://localhost:8080/ls?path=/var/log&args=-l&format=json"
```

---

### 4. Disk Usage (`/du` or `/diskusage`)
Calculates disk usage for directories and files recursively, supporting depth limitation, human-readable formatting, summarization, and threshold filtering.

- **URL:** `/du`
- **Method:** `GET` / `POST`
- **Parameters:**
  - `path`: Target directory or file path (defaults to `.`)
  - `args`: Flags:
    - `-d <N>` / `--max-depth=<N>`: Max directory depth level to output
    - `-h` / `--human-readable`: Human-readable sizes (`4.0K`, `12.5M`, `1.2G`)
    - `-a` / `--all`: Include files as well as directories
    - `-s` / `--summarize`: Display only total size for the target (depth 0)
    - `-t` / `--time`: Display last modification timestamp
    - `-t <SIZE>` / `--threshold=<SIZE>`: Exclude entries smaller than size (e.g. `-t 1M`, `-t 500K`)
  - `format`: `text` (default standard du table) or `json`

**Examples:**
```bash
# Summarize total directory size in human-readable format
curl "http://localhost:8080/du?path=.&args=-sh"

# Disk usage up to depth 1 (immediate subdirectories)
curl "http://localhost:8080/du?path=c:/dir1/&args=-d 1 -h"

# All files and directories with timestamps
curl "http://localhost:8080/du?path=/var/log&args=-ah -t"

# Filter items larger than 10MB in JSON format
curl "http://localhost:8080/du?path=.&args=-t 10M&format=json"
```

---

### 5. Remove File or Directory (`/rm`)
Deletes a file or directory.

- **URL:** `/rm`
- **Method:** `GET` / `POST` / `DELETE`
- **Parameters:**
  - `path`: Path to file or directory
  - `args`: `-r` (recursive), `-f` (force)

**Examples:**
```bash
# Delete file
curl "http://localhost:8080/rm?path=temp.txt&args=-f"

# Delete directory recursively
curl "http://localhost:8080/rm?path=/tmp/testdir&args=-rf"
```

---

### 6. Move or Rename (`/mv`)
- **URL:** `/mv`
- **Parameters:** `from` (src), `end` (to/dst)
```bash
curl "http://localhost:8080/mv?from=c:/dir1/a.txt&end=c:/dir1/b.txt"
```

---

### 7. Create Directory (`/mkdir`)
- **URL:** `/mkdir`
- **Parameters:** `path`, `args` (`-p`)
```bash
curl "http://localhost:8080/mkdir?path=c:/dir1/subfolder&args=-p"
```

---

### 8. File Metadata & Stats (`/stat`)
- **URL:** `/stat?path=<path>`
```bash
curl "http://localhost:8080/stat?path=data.bin"
```

---

### 9. Working Directory & OS Info (`/pwd`)
- **URL:** `/pwd`
```bash
curl "http://localhost:8080/pwd"
```