Categorygithub.com/lemondevxyz/ft
repositorypackage
0.1.3
Repository: https://github.com/lemondevxyz/ft.git
Documentation: pkg.go.dev
Overview
Dependencies
5
Dependents
0

# README

ft

ft is a file browser that allows for file operations remotely. ft has a server/client model and this is the server.

features

  • Creating Directories
  • Copying files & directories
  • Removing files & directories
  • Moving or renaming files and directories
  • Notification of real-time updates that happen to the filesystem
  • Verifying files
  • Pausing, Resuming and cancelling opeartions
  • Adding more files to the operations or removing operations
  • Manual transfer speed limit
  • OpenAPI specification

non-features

  • Authentication; should be done by an outside application
  • Mounting or unmounting filesystems; if wanted, should be done by an outside application
  • Any execution mechanism for file
  • File Transfer History; if wanted, should be implemented by the client but not the server
  • Exposing the file system to other protocols; use sshd, 9p or webdav-daemon

usage

Build it through go build then invoke the command:

# replace $DIR with the directory you want
# to expose 
ft "$DIR"
# do note: any directory inside $DIR that's linked
# to an outside directory won't work

By default, ft is exposed to every ip address and at port 8080. However, this behaivor is customizable through setting the variable FT_ADDR.

The FT_ADDR can be made to listen to either TCP or Unix sockets. Checkout the following example:

# listens on unix socket /tmp/ok.sock
FT_ADDR="unix!/tmp/ok.sock"
# listens on tcp socket 127.0.0.1:12345
FT_ADDR="tcp!127.0.0.1:12345"

api

The API is simple; there are two "sections" of the API. The operation section of the API, mounted at "/api/v0/op". And the file system section of the API, mounted at "/api/v0/fs".

Do note: Operation refers to a copying operation, like copying a directory or a handful of files to another directory.

Operations contain an array of paths that could point to either a file or a directory.

The operation section has these routes:

  • POST /api/v0/op/new: Creates a new operation
  • POST /api/v0/op/status: Changes the status of the operation (For example, pauses the operation)
  • POST /api/v0/op/proceed: A special router that's called after an error occurs
  • POST /api/v0/op/set-sources: Sets the sources(files and directories to copy) of the operation
  • POST /api/v0/op/set-index: Sets the current file to copy by its index in the sources array; can be used to skip a file or two

Do note: In ft's api, you are not supposed to request data about operations. You receive it from the /sse route and save it in the application's memory. This is to ensure multiple clients can use ft without any syncing issues.

The filesystem section has these routes:

  • POST /api/v0/fs/remove: Removes a file or directory and all of its files
  • POST /api/v0/fs/move: Moves a file or directory
  • POST /api/v0/fs/mkdir: Creates a directory
  • POST /api/v0/fs/readdir: Reads a directory and returns its files
  • POST /api/v0/fs/verify: Verifies if two files contents are the same
  • POST /api/v0/fs/size: Calculates the real size of a directory

Do note: /api/v0/fs/readdir can be cached through the ETag Header that it sends. In-fact, in ft-client ReadDir calls are rarely repeated.

Lastly, there are two also important routes. One being the /sse, which sends server-side events (SSE) to the client. Another being the /files route, which exposes the files in the file system to the user for downloading them and possibly executing them.