Jason Transfer Protocol — JTP/1.0
December 28, 2025
Jason Transfer Protocol ("JTP") is a compact request/response protocol for listing and transferring images over TCP (optionally TLS), keyed by xxHash64-derived IDs.
# Abstract
JTP is a lightweight binary protocol for fast image distribution. A client first discovers available content with a catalog request (LIST), then requests one or more images by their content-derived identifiers (GET_BY_ID). Images are addressed by the first 8 bytes of xxHash64 over the file bytes, enabling deduplication and integrity checks; optional TLS provides confidentiality on the wire.
# Connection
- Transport is TCP, optionally wrapped in TLS.
- The reference server listens on 127.0.0.1:8443.
# ImageID encoding
ImageID is 8 bytes (64-bit): the output of xxHash64 over the raw file bytes (seed = 0).
image_bytes = read_file("jason.jpg")
image_id_u64 = xxHash64(image_bytes, seed=0)
image_id_bytes = to_be_bytes(image_id_u64) // 8 bytes# Client request packets
The first byte is ReqType.
3.1 LIST (ReqType = 1)
| Field | Size (bytes) | Description |
|---|---|---|
| ReqType | 1 | 1 = LIST |
3.2 GET_BY_ID (ReqType = 0)
| Field | Size (bytes) | Description |
|---|---|---|
| ReqType | 1 | 0 = GET_BY_ID |
| Count | 1 | Number of IDs (N) |
| ImageID | 8 × N | Requested image IDs |
3.3 BATCH (ReqType = 2, delta sync)
Client sends the IDs it already has; server returns only the missing images.
| Field | Size (bytes) | Description |
|---|---|---|
| ReqType | 1 | 2 = BATCH |
| HaveCount | 1–5 | Have ID count (u32 varint) |
| ImageID | 8 × N | IDs the client already has |
# Server response packets
4.1 LIST response (Header = JTPL)
| Field | Size (bytes) | Description |
|---|---|---|
| Header | 4 | ASCII "JTPL" |
| Count | 2 | Number of entries (u16) |
| Entries | variable | Repeated Count times |
Each entry:
| Field | Size (bytes) | Description |
|---|---|---|
| ImageID | 8 | Image ID (u64, big-endian) |
| Flags | 1 | bits 0..2=file type, bit3=compressed, bit4=encrypted |
| NameLen | 2 | Filename length (u16) |
| Filename | NameLen | UTF-8 basename |
| Size | 1–5 | Data size (u32 varint) |
4.2 Image response
| Field | Size (bytes) | Description |
|---|---|---|
| Flags | 1 | bits 0..2=file type, bit3=compressed, bit4=encrypted |
| Length | 1–5 | Data length (u32 varint) |
| ImageID | 8 | Echoes requested ImageID (u64) |
| Data | variable | Raw file bytes |
4.3 BATCH response (Header = JTPB)
| Field | Size (bytes) | Description |
|---|---|---|
| Header | 4 | ASCII "JTPB" |
| MissingCount | 1–5 | Missing image count (u32 varint) |
| Images | variable | Repeated MissingCount times (image response) |
# Example packets
Hex dumps are spaced by byte. Fixed-width integers are big-endian; sizes/lengths are unsigned LEB128 varints.
1.1. LIST request
01
- 01 = ReqType (LIST)
1.2. LIST response (Count = 1)
4A 54 50 4C 00 01 AA BB CC DD EE FF 00 11 01 00 09 6A 61 73 6F 6E 31 2E 6A 70 67 B4 24
- JTPL header, Count=1
- Entry: ImageID(8) + Flags(01=jpg) + NameLen(9)
- Filename 'jason1.jpg' + Size(0x00001234 varint)
2.1. GET_BY_ID request (Count = 1)
00 01 AA BB CC DD EE FF 00 11
- 00 = ReqType (GET_BY_ID)
- 01 = Count
- 8 bytes of ImageID
2.2. Response: image packet
01 04 AA BB CC DD EE FF 00 11 DE AD BE EF
- Flags(01=jpg) + Length(4 varint)
- ImageID echoes the requested ID (8 bytes)
- 4 bytes of file data (example)