KittyPatch/kitty
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Document the escape code format for the file transmission protocol

Browse Source
This commit is contained in:
Kovid Goyal 2021-11-18 21:19:56 +05:30
parent 5f4e326985
commit d47a80c8e8
No known key found for this signature in database
GPG Key ID: 06BC317B515ACE7C
2 changed files with 60 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
docs/file-transfer-protocol.rst
View File

@ -108,3 +108,62 @@ creating links, etc. If any errors occur it responds with an error message,
such as::
← action=status id=someid status=Some error occurred
Encoding of transfer commands as escape codes
------------------------------------------------
Transfer commands are encoded as OSC escape codes of the form::
<OSC> 5113 ; key=value ; key=value ... <ST>
Here ``OSC`` is the bytes ``0x1b 0x5d`` and ``ST`` is the bytes
``0x1b 0x5c``. Keys are words containing only the characters ``[a-zA-Z0-9_]``
and ``value`` is arbitrary data, whose encoding is dependent on the value of
``key``. Unknown keys **must** be ignored when decoding a command.
The number ``5113`` is a constant and is unused by any known OSC codes. It is
the numeralization of the word ``file``.
.. table:: The keys and value types for this protocol
:align: left
================= ======== ============== =======================================================================
Key Key name Value type Notes
================= ======== ============== =======================================================================
action ac Enum send, file, data, end_data, receive, cancel, status, finish
compression zip Enum none, zlib
file_type ft Enum regular, directory, symlink, link
transmission_type tt Enum simple, rsync
id id safe_string A unique-ish value, to avoid collisions
file_id fid safe_string Must be unique per file in a session
bypass pw safe_string hash of the bypass password and the session id
quiet q integer 0 - verbose, 1 - only errors, 2 - totally silent
mtime mod integer the modification time of file in nanoseconds since the UNIX epoch
permissions prm integer the UNIX file permissions bits
size sz integer size in bytes
name n base64_string The path to a file
status st base64_string Status messages
parent pr safe_string The file id of the parent directory
data d base64_bytes Binary data
================= ======== ============== =======================================================================
Here:
Enum
One from a permitted set of values, for example::
ac=file
safe_string
A string consisting only of characters from the set ``[0-9a-zA-Z_:.,/!@#$%^&*()[]{}~`?"'\\|=+-]``
integer
A base-10 number composed of the characters ``[0-9]`` with a possible
leading ``-`` sign
base64_string
A base64 encoded UTF-8 string using the standard base64 encoding
base64_bytes
Binary data encoded using the standard base64 encoding

2
kitty/file_transmission.py
View File

@ -266,7 +266,7 @@ class FileTransmissionCommand:
size: int = field(default=-1, metadata={'sname': 'sz'})
name: str = field(default='', metadata={'base64': True, 'sname': 'n'})
status: str = field(default='', metadata={'base64': True, 'sname': 'st'})
parent: str = field(default='', metadata={'base64': True, 'sname': 'pr'})
parent: str = field(default='', metadata={'sname': 'pr'})
data: bytes = field(default=b'', repr=False, metadata={'sname': 'd'})
def __repr__(self) -> str: