Files: put, read and the disk driver in development

This topic has the exact rules for File fields, store.put, store.read, and the store jadpo dev and tests keep files in (Files has the overview).

What a File holds

A File holds the connection its bytes are in, the key the runtime made for them, its name (none for one store.put made), its size and its FileType. It is kept as its JSON in a jsonb column.

Only the runtime builds one: File { ... } is type.not_record. No request carries a File, and no output sends one, since an output's signed link comes with downloads. A program reads none of its parts yet.

A File field's settings

• store: must name a connection that provides files.
• max_size: is required: a whole number of b, kb, mb or gb, each a thousand times the last. 5mb is 5,000,000 bytes, which is why this page writes "100 MB" apart from "16 MiB".
• types: is optional.

A mistake in any of them is data.file_field_invalid. The three settings on a field that isn't a File are type.unknown_setting.

store.put(bytes, type)

You call store.put only in an action, before its first write, as every outside call is made. Its key is made from the invocation's randomness, so a replay keeps it. It goes out as a keyed call, since writing the same key again writes the same object, which never changes.

A store with no room answers storage_full, the call's one condition. Its attempt maps it to a failure of kind unavailable; it isn't a fault of a value, so invalid: doesn't cover it. A store that can't be reached is the runtime's own unavailable.

store.read(file)

store.read reads at most 10 MB into memory. Reading a field whose max_size is over that is type.file_read_too_large, where it is read. A File whose field isn't known, such as a parameter of type File, is held to the limit as it runs, and going over it is a fault. A file whose bytes are gone from its store is a fault too.

FileContents is the file's bytes. Nothing takes it yet but what passes bytes on, such as an email's attachment or a provider's upload. Like put, read is called only in an action, before its first read or write. A test reaches files through the application's actions.

The disk driver in jadpo dev

jadpo dev keeps every store of files under .jadpo/files/<connection>/, whatever its driver, so nothing leaves your machine:

• Each file is kept under its key, sharded into two directory levels by its id. A key of any other shape is refused, and so is a symbolic link anywhere on the way.
• A file is written to a temporary file readable by the application's user only, synced, and renamed into place, and its folder is synced.
• A full disk answers storage_full.

Its reads and writes block, a window of at most a megabyte at a time, on your own disk.

Files in a test

In a test, one in-memory store serves every connection (Provider calls and capabilities in tests), and a file helper's run reads two rows a batch. fixture_file, and telling the store to fail from a test's source, come with the testing fakes (What is built).