Skip to main content

Module storage

Module storage 

Source
Expand description

Putting a file into the platform’s store, and reading one back out.

Two ways in — bytes this action already holds, and a file behind a URL — and one thing out of both: a DocumentHandle, which is the value a :document field holds. The way out is read, which takes that handle and answers with the file’s bytes.

use simpleplatform_sdk::storage::Target;

let target = Target::new("dev.simple.system", "documents", "attachment");
let handle = simple::storage::upload_buffer(b"foobar", "report.pdf", "application/pdf", target)?;

assert_eq!(handle.filename, "report.pdf");
assert_eq!(handle.size, 6);

§The handle is the point

An upload stores the file and answers with a handle to it. Attaching that handle to a record is a separate step, and the one that changes tenant data: write the handle into the :document field with crate::graphql::mutate once you have it. So the two halves stay separable — the file is in the store whether or not the record was written, and the store is the only thing upload_buffer and upload_external touch.

§The same bytes are the same file

The store is addressed by the SHA-256 of the contents, which is the file_hash on the handle. Identical bytes land under the identical hash and are kept once, so uploading a file the store already holds costs a hash and answers with the handle that was already there.

§Reading a file back

let bytes = simple::storage::read(&handle)?;

assert_eq!(bytes, file);

The bytes cross from the host as they are, with no JSON and no base64. The size is asked for first, the buffer is allocated once at exactly that size, and the file arrives in ranges of at most MAX_RANGE_BYTES, each written by the host straight into its place in that buffer. read_range reads part of a file the same way, from the size first, and size answers how large it is without reading any of it.

Reading is for server actions. A browser action is refused.

§Why the bytes are encoded here

The call travels as JSON, and JSON carries text. So a buffer is base64 on the wire — encoded once, at this boundary, in the same standard alphabet with the same padding every SDK uses, and decoded by the platform before the file is stored. An action passes &[u8] and never sees the encoding.

Structs§

DocumentHandle
A stored file, as a :document field holds it.
Source
The file an external upload reads.
Target
The record field a stored file is destined for.

Enums§

Auth
The credential a URL is read with.

Constants§

MAX_RANGE_BYTES
The longest range the host answers one read with.

Functions§

read
The whole of a stored file.
read_range
Up to length bytes of a stored file, starting offset bytes in.
size
How many bytes a stored file holds, from the store’s own record of it.
upload_buffer
Store bytes this action already holds.
upload_external
Store a file the platform reads from a URL.