VSP1 protocol

VSP1 is a request/response protocol over a Unix stream socket. Each connection carries exactly one request. Text headers are US-ASCII and end in \n; payloads are raw bytes.

Limits

• Header: 1,023 bytes excluding terminator.
• Name: 1–128 bytes, [A-Za-z_][A-Za-z0-9_]*.
• Secret: 1–1,048,576 bytes.
• Token: exactly 64 hexadecimal characters representing 32 random bytes.
• Live entries: 4,096.
• TTL: 1 ms through 365 days.

Responses

Success:

OK <payload_length>\n<payload>

Failure:

ERR <CODE> <human-readable-message>\n

Error codes are stable machine identifiers: INVALID, NOT_FOUND, EXPIRED, FORBIDDEN, FULL, NO_MEMORY, IO, PEER, PROTOCOL, and INTERNAL.

PING

VSP1 PING\n

Response: OK 0\n.

PUT

VSP1 PUT <ttl_ms> <uses> <scope> <name_length> <secret_length>\n
<name><secret>

The broker derives the owner UID from the socket peer. scope is:

• 0: any process with the owner UID;
• positive PID: exactly that process;
• negative process-group ID: any process currently in that group.

On platforms where peer PID is unavailable, non-zero scopes cannot be redeemed.

Success payload is the 64-byte capability token.

GET

VSP1 GET <token>\n

The broker verifies UID, optional scope, TTL and remaining uses. It atomically decrements the use count before returning the value. A client that disconnects during delivery still consumes that use; this prevents replay ambiguity.

Success payload is the exact secret bytes.

DROP

VSP1 DROP <token>\n

Only the owner UID can delete an entry. Success has no payload.

STATS

VSP1 STATS\n

Response payload:

{"entries":1,"limit":4096}

No names, values, tokens, TTLs or process identifiers are returned.

Compatibility

Clients must reject unknown response formats and excessive lengths. Future protocol versions will use a different prefix (VSP2, etc.); VSP1 servers reject them rather than guessing.

Source