Module storage 

Storage: save slots and other per-user key-value objects. Routes: routes::storage.

An object lives at (owner, collection, key) and holds one JSON value (a save game, settings, an inventory snapshot). Every route addresses the CALLER’s own objects; in 0.1.0 nobody reads another user’s objects (a later version may add public objects with an owner in the path).

Versions. Every write bumps the object’s ObjectVersion (1 for a new object). The default is last write wins. A write that names the version it expects (PutObject::if_version) is refused with 409 codes::VERSION_CONFLICT and a VersionConflict in details if the stored version differs, and nothing changes: only then two devices cannot silently overwrite each other’s save. ObjectVersion::ABSENT means “only if it does not exist yet”. The body field is the primary form; the server also honours If-Match: "N" and If-None-Match: * on single-object PUT / DELETE (400 if header and body disagree) and always sends the version as an ETag header ("3").

Delete is idempotent: deleting an object that does not exist answers Ack, unless if_version names a version (then 409 version_conflict).

Write access. WriteAccess::Server objects (set only by server-side game code, never by a client request) refuse client writes with 403.

Body budget. bevy_net_backend refuses answers over 10 MiB by default. Single objects are at most DEFAULT_MAX_OBJECT_BYTES (256 KiB); a batch carries at most MAX_BATCH objects and MAX_BATCH_BYTES (4 MiB) of values, so a batch answer stays near 4 MiB; collection listings return StorageObjectInfo (no values: ~200 bytes each × 100 = ~20 KB). Request body limits the server sets: PUT_BODY_LIMIT_BYTES, BATCH_BODY_LIMIT_BYTES, everything else routes::DEFAULT_BODY_LIMIT_BYTES.

Binary data: the value is JSON; put bytes in a string (e.g. base64, +33 %: it counts against the size limit) yourself.

Structs

BatchAcks

The answer to a BatchPut: one acknowledgement per write, in request order.

BatchGet

Read several of the caller’s objects: POST /v1/storage/_batch/get → BatchObjects.

BatchObjects

The answer to a BatchGet: the objects that exist (missing ones are simply absent), at most MAX_BATCH_BYTES of values.

BatchPut

Write several objects in one transaction: POST /v1/storage/_batch/put → BatchAcks. All or nothing: one failed condition or rule fails the whole batch (a version conflict names the first failing item: VersionConflict::index).

BatchPutItem

One write in a BatchPut.

DeleteObject

Delete one object: DELETE /v1/storage/{collection}/{key}?if_version=3 → Ack.

GetObject

Read one of the caller’s objects: GET /v1/storage/{collection}/{key} → StorageObject (the ETag header carries its version).

ListObjects

List the caller’s objects in a collection: GET /v1/storage/{collection}?cursor=…&limit=… → Page<StorageObjectInfo> (no values; ordered by key).

ObjectAck

The answer to a write: where it went and its new version.

ObjectRef

One object to read in a BatchGet.

ObjectVersion

An object’s version: 1 after the first write, +1 on every write.

PutObject

Write one object: PUT /v1/storage/{collection}/{key} → ObjectAck.

RemoveObject

Delete one of the caller’s objects: DELETE /v1/storage/{collection}/{key}?if_version=… → Ack (idempotent without if_version).

StorageObject

A stored object with its value: GET /v1/storage/{collection}/{key} and batch reads.

StorageObjectInfo

An object without its value: the items of GET /v1/storage/{collection} (a listing stays small whatever the values weigh; read the values with a GET or a batch get).

VersionConflict

The details of a 409 codes::VERSION_CONFLICT.

WriteObject

Write one of the caller’s objects: PUT /v1/storage/{collection}/{key} with a PutObject → ObjectAck.

Enums

WriteAccess

Who may write an object (read-only for clients: they see it, server-side game code sets it).

Constants

BATCH_BODY_LIMIT_BYTES

The request body limit for a batch put: the values plus room for the item envelopes.

DEFAULT_MAX_OBJECTS_PER_USER

The default number of objects one user may own (the server may configure another).

DEFAULT_MAX_OBJECT_BYTES

The default largest value, in bytes of its JSON (256 KiB; the server may configure less, or more as long as a batch read stays within MAX_BATCH_BYTES).

MAX_BATCH

The most objects in one batch request.

MAX_BATCH_BYTES

The most value bytes (sum of the values’ JSON) in one batch, written or read. A batch read whose objects exceed it is refused with 413 payload_too_large (read fewer objects per batch).

MAX_NAME_BYTES

The longest collection name or key, in bytes.

PUT_BODY_LIMIT_BYTES

The request body limit for a single-object PUT: the value plus room for the envelope.

Functions

is_valid_name

Whether name is a valid collection name or key: 1 to MAX_NAME_BYTES bytes of ASCII letters, digits, _, - and ., starting with a letter or digit. Valid names are safe in a URL path without escaping (and cannot be ., .. or _batch).

value_bytes

The size of a value: the length of its JSON.