PaperCache

Wire protocol

The following is a description of PaperCache's wire protocol. This is useful when creating a new client. All values are encoded in little-endian. All strings are UTF-8 encoded. Each response is preceeded by a status byte (u8) where 33 is OKAY, and 63 is NOT OKAY.

CommandDescriptionRequestOKAY response
PING Sends a ping request to the server. Useful for health checks.
  • 0 (u8)
  • <length> (u32)
  • pong (u8[])
VERSION Requests the version number of the cache.
  • 1 (u8)
  • <length> (u32)
  • <version> (u8[])
AUTH Authorizes the client with the server if an auth_token has been configured.
  • 2 (u8)
  • <token> (u8[])
GET Gets the value of the supplied key if it exists, otherwise returns an error value.
  • 3 (u8)
  • <key length> (u32)
  • <key> (u8[])
  • <value length> (u32)
  • <value> (u8[])
SET Sets a new value with the supplied key. The TTL value is in seconds (a TTL value of 0 indicates no expiry).
  • 4 (u8)
  • <key length> (u32)
  • <key> (u8[])
  • <value length> (u32)
  • <value> (u8[])
  • <ttl> (u32)
DEL Deletes an object if it exists, otherwise returns an error value.
  • 5 (u8)
  • <key length> (u32)
  • <key> (u8[])
HAS Checks if a value with the supplied key exists.
  • 6 (u8)
  • <key length> (u32)
  • <key> (u8[])
  • 0 (u8, 0 = false, 1 = true)
PEEK Gets the value of the supplied key if it exists, otherwise returns an error value. Unlike GET, PEEK does not modify the order of the eviction policy stack upon access.
  • 7 (u8)
  • <key length> (u32)
  • <key> (u8[])
  • <value length> (u32)
  • <value> (u8[])
TTL Sets the TTL of the supplied key if it exists, otherwise returns an error value. The TTL value is in seconds (a TTL value of 0 indicates no expiry).
  • 8 (u8)
  • <key length> (u32)
  • <key> (u8[])
  • <ttl> (u32)
SIZE Gets the size of the value of the supplied key if it exists, otherwise returns an error value.
  • 9 (u8)
  • <key length> (u32)
  • <key> (u8[])
  • <size> (u32)
WIPE Deletes all data from the cache.
  • 10 (u8)
RESIZE Resizes the cache.
  • 11 (u8)
  • <size> (u64)
POLICY Sets the cache's eviction policy.
  • 12 (u8)
  • <policy length> (u32)
  • <policy> (u8[])
STATUS Gets the cache's status.
  • 13 (u8)
  • <pid> (u32)
  • <max size> (u64)
  • <used size> (u64)
  • <num objects> (u64)
  • <rss> (u64)
  • <hwm> (u64)
  • <total GETs> (u64)
  • <total SETs> (u64)
  • <total DELs> (u64)
  • <miss ratio> (f64)
  • <num policies> (u32)
  • <policies> ((<policy length> (u32), <policy> (u8[]))[num policies])
  • <policy length> (u32)
  • <policy> (u8[])
  • <is auto policy> (u8, 0 = false, 1 = true)
  • <uptime> (u64, milliseconds)

Errors

The following is a description of PaperCache's error wire protocol. If the initial byte of any response is NOT OKAY (63), the following can be used to parse the subsequent bytes.

Error typeDescriptionNOT OKAY response
INTERNAL An internal error has occurred.
  • 1 (u8)
MAX_CONNECTIONS_EXCEEDED The maximum number of concurrent client connections has been exceeded.
  • 2 (u8)
UNAUTHORIZED The client is not authorized to perform the action. Use the 'auth' command to authorize the client.
  • 3 (u8)
INTERNAL_CACHE_ERROR An internal error occurred in the cache itself (not the TCP server).
  • 0 (u8)
  • 0 (u8)
KEY_NOT_FOUND The requested key was not found in the cache.
  • 0 (u8)
  • 1 (u8)
ZERO_VALUE_SIZE The provided value has zero size.
  • 0 (u8)
  • 2 (u8)
EXCEEDING_VALUE_SIZE The provided value's size exceeds the size of the cache.
  • 0 (u8)
  • 3 (u8)
ZERO_CACHE_SIZE The provided cache size is zero.
  • 0 (u8)
  • 4 (u8)
UNCONFIGURED_POLICY The provided policy is not configured in the cache.
  • 0 (u8)
  • 5 (u8)
INVALID_POLICY The provided policy is invalid.
  • 0 (u8)
  • 6 (u8)