File Streaming Protocol

A protocol for remote file system access with resumable transfers and real-time watching.

What is the File Streaming Protocol?

The File Streaming Protocol enables remote file system operations over HTTP with built-in resumability. Unlike traditional file transfer protocols, large file transfers can be paused and resumed from any point, and directory changes can be watched in real-time.

Built on top of Unbroken Protocol, it combines:

Standard HTTP methods for familiar REST semantics
Unbroken Protocol for resumable transfers
SSE for real-time file watching

Key Features

Feature	Description
Resumable	Resume interrupted transfers from exact byte position
Streamable	Large files streamed without memory limits
Watchable	Real-time notifications via SSE
Web Native	Standard HTTP methods and headers
CDN Friendly	Cacheable responses with ETags

Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Client                               │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │    File     │    │  Directory  │    │    Watch    │     │
│  │   Reader    │    │   Browser   │    │  Listener   │     │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘     │
└─────────┼──────────────────┼──────────────────┼─────────────┘
          │ GET              │ GET/             │ GET?live=sse
          ▼                  ▼                  ▼
┌─────────────────────────────────────────────────────────────┐
│                      File Server                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │    File     │    │  Directory  │    │     FS      │     │
│  │   Storage   │    │   Index     │    │   Watcher   │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
└─────────────────────────────────────────────────────────────┘

Quick Example

# Create a file
curl -X PUT http://localhost:9999/files/hello.txt \
  -H "Content-Type: text/plain" \
  -d "Hello, World!"

# Read a file
curl http://localhost:9999/files/hello.txt

# List directory
curl http://localhost:9999/files/

# Watch for changes (SSE)
curl "http://localhost:9999/files/?live=sse"

# Delete a file
curl -X DELETE http://localhost:9999/files/hello.txt

Protocol at a Glance

Endpoints

Method	Path	Description
`PUT`	`/files/{path}`	Create or update file
`PUT`	`/files/{path}/`	Create directory
`GET`	`/files/{path}`	Read file content
`GET`	`/files/{path}/`	List directory
`GET`	`/files/{path}?live=sse`	Watch for changes
`DELETE`	`/files/{path}`	Delete file or directory
`HEAD`	`/files/{path}`	Get file metadata
`POST`	`/files/{path}?op=copy&to={dest}`	Copy file
`POST`	`/files/{path}?op=move&to={dest}`	Move/rename file

Headers

Header	Direction	Description
`Content-Length`	Response	File size in bytes
`Last-Modified`	Response	Modification timestamp
`ETag`	Response	Content hash for caching
`Content-Type`	Both	MIME type of content
`Range`	Request	Byte range for partial reads
`Stream-Next-Offset`	Response	Resume position
`File-Type`	Response	`file` or `directory`

Watch Events (SSE)

Event	Description
`created`	New file or directory created
`modified`	File content changed
`deleted`	File or directory deleted
`renamed`	File or directory renamed
`snapshot`	Initial directory state
`ready`	Snapshot complete, live events follow

Path Conventions

Paths are URL-encoded and relative to server root
Trailing slash / indicates directory
No trailing slash indicates file
Path traversal (../) is rejected

Use Cases

Remote Development: Access project files over HTTP
Cloud Storage: S3-like object storage API
File Sync: Real-time sync with watch events
Media Streaming: Resumable video/audio delivery
Backup Systems: Large file transfers with resume

Specification

For the complete protocol specification, see PROTOCOL.md.

Default Port

The file server uses port 9999/tcp by default (same as Unbroken Protocol).

Requirements

Server: Bun or Node.js runtime
Client: Any HTTP client (browser, curl, custom)