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§
- Document
Handle - A stored file, as a
:documentfield 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
lengthbytes of a stored file, startingoffsetbytes 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.