Protocol Verbs

File transfers

File transfers: part of the Protocol Verbs of TUIOS.

This page is one part of docs/protocol-verbs.md of the tuios repository. The Protocol Verbs page lists every part.

file-commit Added in v0.9.3

Finish a copy written with open-file-stream: check the part's sha256 against the sender's, then rename it into place. A part that does not match is removed.

ParamTypeRequiredDefaultDescription
pathstringyesThe file the copy is for. An absolute path, or one that starts with ~.
sha256stringThe sender's hash, hex. Omit to skip the check.
conflictstringfailWhen the path exists: replace it, keep both (the copy gets a new name), skip (the part is removed and the file there stays), or fail. One of replace, keep-both, skip or fail.
labelstringkeep-both names the copy "name (LABEL).ext", such as "report (from build).pdf". Omit to name it "name 2.ext".
permintThe original's permission bits, which the finished file gets. Omit to keep it owner only.
mtimeintThe original's modification time, Unix ms, which the finished file gets. Omit to keep the time of the copy.
part_idstringThe copy's part id, up to 32 hex digits: the part is .NAME.tuios-part-ID, so two copies to one path write two parts. Omit for .NAME.tuios-part.
Result fieldTypeDescription
pathstringWhere the file is now.
sha256stringThe part's hash.
skippedboolconflict skip found a file at path, so the copy was removed and the file there stays.
{"id":1,"verb":"file-commit","params":{"path":"~/big.iso","sha256":"9f86d0...","conflict":"keep-both"}}

file-drop-dir Added in v0.9.3

Make a private folder on this machine for files dropped on a pane, and answer its path. Drops are kept for 24 hours and 256 MiB together, oldest removed first.

ParamTypeRequiredDefaultDescription
bytesintThe size of the drop, so older drops make room for it.
Result fieldTypeDescription
dirstringThe new folder, owner only.
keep_bytesintHow many bytes the drops together may hold.
keep_hoursintHow long a drop is kept.
{"id":1,"verb":"file-drop-dir","params":{"bytes":1048576}}

file-hash Added in v0.9.3

The sha256 of a file on this machine, of a range of it, or of the part a copy to it is writing.

ParamTypeRequiredDefaultDescription
pathstringyesThe file. An absolute path, or one that starts with ~.
offsetint0Where the range starts.
lengthintHow many bytes. Omit for the rest of the file.
partboolHash the part file of a copy to this path.
part_idstringThe copy's part id, up to 32 hex digits: the part is .NAME.tuios-part-ID, so two copies to one path write two parts. Omit for .NAME.tuios-part.
Result fieldTypeDescription
sha256stringThe hash, hex.
bytesintHow many bytes were hashed.
{"id":1,"verb":"file-hash","params":{"path":"~/big.iso"}}

file-list Added in v0.9.3

List a folder on this machine a page at a time, folders first, then names in natural order (file2 before file10), with size, time and mode.

ParamTypeRequiredDefaultDescription
dirstringThe folder. Omit for the home folder.
offsetint0The first entry of the page.
limitint500Entries in the page, at most 5000.
hiddenbooltrueInclude names that start with a dot.
Result fieldTypeDescription
dirstringThe folder, made absolute.
entries[]objectOne info object per entry, as file-stat's info.
totalintEntries in the folder.
nextintThe offset of the next page. Absent on the last page.
parentstringThe folder above. Absent at the root.
homestringThis machine's home folder.
cappedboolThe folder holds more than 50000 names, and only those were read.
{"id":1,"verb":"file-list","params":{"dir":"~/src","limit":200}}

file-mkdir Added in v0.9.3

Make a folder on this machine, with its parents.

ParamTypeRequiredDefaultDescription
pathstringyesThe folder. An absolute path, or one that starts with ~.
receiveboolMake the receive folder instead, and ignore path: where a copy from the caller lands when it names no folder. For a linked machine it is the first folder of its files_roots, else ~/Downloads/tuios.
Result fieldTypeDescription
pathstringThe folder, made absolute.
{"id":1,"verb":"file-mkdir","params":{"path":"~/new"}}
{"id":2,"verb":"file-mkdir","params":{"path":"~","receive":true}}

file-read Added in v0.9.3

Read up to 4 MiB of a file on this machine, base64.

ParamTypeRequiredDefaultDescription
pathstringyesThe file. An absolute path, or one that starts with ~.
offsetint0Where to start.
lengthint4194304How many bytes, at most 4 MiB.
Result fieldTypeDescription
contentstringThe bytes, base64.
sizeintThe file's size.
eofboolThe read reached the end of the file.
{"id":1,"verb":"file-read","params":{"path":"~/notes.md","length":65536}}

file-remove Added in v0.9.3

Delete a path on this machine. A folder that holds files needs recursive. The home folder and / are refused.

ParamTypeRequiredDefaultDescription
pathstringyesThe path. An absolute path, or one that starts with ~.
recursiveboolDelete a folder and all it holds.
Result fieldTypeDescription
pathstringThe path deleted.
{"id":1,"verb":"file-remove","params":{"path":"~/old","recursive":true}}

file-rename Added in v0.9.3

Move or rename a path on this machine. It does not replace a path that is there unless replace is set. A move to another disk answers cross_device: copy it with transfer-start and move set.

ParamTypeRequiredDefaultDescription
fromstringyesThe path to move.
tostringyesThe new path.
replaceboolReplace what is at to.
Result fieldTypeDescription
fromstringThe old path.
tostringThe new path.
{"id":1,"verb":"file-rename","params":{"from":"~/a.txt","to":"~/b.txt"}}

file-stat Added in v0.9.3

Describe one path on this machine. With part, describe the part file a copy to the path is writing.

ParamTypeRequiredDefaultDescription
pathstringyesThe path. An absolute path, or one that starts with ~.
partboolDescribe the part file of a copy to this path instead.
part_idstringThe copy's part id, up to 32 hex digits: the part is .NAME.tuios-part-ID, so two copies to one path write two parts. Omit for .NAME.tuios-part.
relation_tostringAnother path on this machine. The reply says how path stands to it, with links followed.
Result fieldTypeDescription
pathstringThe path, made absolute.
existsboolFalse when nothing is there.
sizeintThe size in bytes. 0 for a part that is not there.
infoobjectname, path, kind (file, dir, symlink, other), link_kind and link for a link, size, mtime (Unix ms), mode (drwxr-xr-x), perm (the permission bits as a number), hidden.
relationstringWith relation_to: same when the two paths are one file, inside when path is in the folder relation_to, apart otherwise.
{"id":1,"verb":"file-stat","params":{"path":"~/notes.md"}}

file-walk Added in v0.9.3

List every file and folder under a folder on this machine, for a folder copy. At most 20000 entries in one reply; with stream, up to 1000000 entries, one JSON line each after the reply, and a last line {end, bytes, skipped, skipped_count, denied} or {end, code, error}. Links are not followed: a link, a named pipe, a socket and a device are not copied, and skipped names them. Over a link, an entry in the read deny list is left out and not named, and denied counts it.

The connection stays open after the reply when stream is true.

ParamTypeRequiredDefaultDescription
pathstringyesThe folder. An absolute path, or one that starts with ~.
streamboolSend the entries after the reply, one JSON line each, for a folder of more than 20000 entries.
Result fieldTypeDescription
entries[]objectrel (the path under the folder, slash separated), size, dir, perm, mtime (Unix ms). A folder comes before what it holds.
bytesintThe bytes of every file together.
skipped[]objectThe first 200 items a copy does not carry: rel and kind (symlink, pipe, socket, device).
skipped_countintHow many items a copy does not carry, all of them.
deniedintOver a link, how many entries were left out because a linked machine may not read them. A folder counts once. They are not named.
{"id":1,"verb":"file-walk","params":{"path":"~/photos"}}

open-file-stream Added in v0.9.3

Turn this connection into the bytes of one file. mode read: after the reply the connection carries the file from offset to size, then closes. mode write: the part file beside path is cut to offset, then the connection takes length bytes into it, answers one line {part_size, written, error} and closes. file-commit puts the part in place.

The connection stays open after the reply.

ParamTypeRequiredDefaultDescription
pathstringyesThe file to read, or the file a write is for. An absolute path, or one that starts with ~.
modestringreadread or write. One of read or write.
offsetint0Where the bytes start. A write's offset cannot be past the part's end.
lengthintwrite only: how many bytes the caller sends.
part_idstringThe copy's part id, up to 32 hex digits: the part is .NAME.tuios-part-ID, so two copies to one path write two parts. Omit for .NAME.tuios-part.
sumboolread: after the last byte, one line {sha256} with the hash of the bytes sent, or {error} when the file changed while it was read.
progressboolwrite: while the bytes land, one line {written} at most every 250 ms with the bytes written so far, before the last line.
compressanyread: "auto" lets this machine compress the bytes with flate when a sample of the file compresses well, and the reply says compressed. write: true when the caller sends the bytes as one flate stream.
Result fieldTypeDescription
sizeintread: the file's size. The connection carries size minus offset bytes.
mtimeintread: the file's modification time, Unix ms.
compressedboolread: the bytes come as one flate stream.
sumboolread: a {sha256} line follows the bytes.
part_sizeintwrite: the part's size before it was cut to offset.
{"id":1,"verb":"open-file-stream","params":{"path":"~/big.iso","mode":"read","offset":0}}
{"id":1,"verb":"open-file-stream","params":{"path":"~/big.iso","mode":"write","offset":1048576,"length":2097152}}

transfer-list Added in v0.9.3

List the transfers, newest first, with byte progress, rate and time left. Finished ones stay for 30 minutes. A pane with the files grant sees only the copies it started.

ParamTypeRequiredDefaultDescription
idstringOnly this transfer.
Result fieldTypeDescription
transfers[]objectOne row per transfer: id, name, src, dst, target, kind, move, state, size, done, wire, rate, eta_ms, files, files_done, current, current_done, current_size, error, code, resumed_from, resumes, sha256, verified, created, started, ended, retry_in_ms, skipped, skipped_items, same, conflicts_skipped, conflicts_left, conflicts, conflict_count, failed_files, pane, pane_session.
activeintTransfers that are not finished.
{"id":1,"verb":"transfer-list"}

transfer-pause Added in v0.9.3

Pause a transfer. What it copied stays, and transfer-resume goes on from there.

ParamTypeRequiredDefaultDescription
idstringyesThe transfer's id.
Result fieldTypeDescription
idstringThe transfer's id.
statestringqueued, running, verifying, waiting (for a machine that went away), paused, conflict (waits for transfer-answer), done, failed or cancelled. One of queued, running, verifying, waiting, paused, conflict, done, failed or cancelled.
sizeintBytes to copy in all.
doneintBytes copied, or found to be there already.
wireintBytes that crossed a link, fewer than done when they were compressed.
ratefloatBytes per second over the last five seconds.
eta_msintTime left, once two seconds of data came.
resumed_fromintWhere the copy went on from after a machine came back. Absent when it never had to.
verifiedboolThe copy's sha256 matched the original's.
finalstringWhere the file is now, which keep-both can change.
sameintFiles that were there with the same bytes, which were not copied again.
conflicts_skippedintFiles that were there and differed, left as they were.
conflicts[]objectIn state conflict: the files that wait for an answer, rel, path, src_size, src_mtime, dst_size, dst_mtime.
errorstringWhat happened and what to do, for failed and waiting.
{"id":1,"verb":"transfer-pause","params":{"id":"3f9a1c2b7d00"}}

transfer-start Added in v0.9.3

Copy a file or a folder between this machine and a host, or between two hosts. The daemon runs the copy, so a client may quit, and a daemon restart goes on with it. A machine that goes away pauses it, and it goes on from where it stopped when the machine is back. Every file's sha256 is checked before it is put in place, and it keeps the original's permission bits and modification time. A file that arrives over a link gets the receiving machine's umask and never group or world write. A file that is there with the same sha256 is not copied again. A destination that exists answers file_exists unless conflict says what to do. A destination another copy writes now answers busy. Each change is a transfer event on the event stream.

ParamTypeRequiredDefaultDescription
srcobjectyesWhat to copy: {host, path}. host is a name from [hosts], or empty for this machine. path is absolute or starts with ~.
dstobjectyesWhere it goes: the full path of the copy, or with place a folder: {host, path}. host is a name from [hosts], or empty for this machine. path is absolute or starts with ~.
moveboolRemove the original once the copy is checked.
conflictstringfailWhen dst exists: replace it, keep both (the copy gets a new name), merge a folder into the folder there, skip a file that differs, ask (the copy waits in state conflict for transfer-answer), or fail. One of replace, keep-both, merge, skip, ask or fail.
eachstringIn a folder copy into a folder that is there: what to do with each file that is there and differs. Omit to follow conflict, which for merge and replace is replace. One of replace, keep-both, skip or ask.
placestringauto reads dst as cp does: a folder that is there gets the copy inside it, and anything else is the new name. into needs dst to be a folder that is there. A dst that ends in / with auto is into. contents copies what a folder holds into dst, and a file as auto does. One of auto, into or contents.
permsbooltrueGive each file the original's permission bits.
timesbooltrueGive each file the original's modification time.
compressbooltrueCompress the bytes on a link when they compress well.
rate_limitint0At most this many bytes a second. 0 for no limit.
keep_frombooltruekeep-both names a copy from another machine "name (from HOST).ext". false numbers it, "name 2.ext".
Result fieldTypeDescription
idstringThe transfer's id.
statestringqueued, running, verifying, waiting (for a machine that went away), paused, conflict (waits for transfer-answer), done, failed or cancelled. One of queued, running, verifying, waiting, paused, conflict, done, failed or cancelled.
sizeintBytes to copy in all.
doneintBytes copied, or found to be there already.
wireintBytes that crossed a link, fewer than done when they were compressed.
ratefloatBytes per second over the last five seconds.
eta_msintTime left, once two seconds of data came.
resumed_fromintWhere the copy went on from after a machine came back. Absent when it never had to.
verifiedboolThe copy's sha256 matched the original's.
finalstringWhere the file is now, which keep-both can change.
sameintFiles that were there with the same bytes, which were not copied again.
conflicts_skippedintFiles that were there and differed, left as they were.
conflicts[]objectIn state conflict: the files that wait for an answer, rel, path, src_size, src_mtime, dst_size, dst_mtime.
errorstringWhat happened and what to do, for failed and waiting.
{"id":1,"verb":"transfer-start","params":{"src":{"host":"build","path":"~/out/image.iso"},"dst":{"path":"~/Downloads/image.iso"}}}

tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.

On this page