`std/storage/storage`

std/storage/src/storage.trb

Storage, the capability, StorageFailure, what a storage refuses with, and the registry Storage.registry answers: one storage over several drivers, itself a storage.

type StorageFailure

type StorageFailure with Show, Equals, Error

What a storage refuses with. Every case carries the reference as Uri.show() wrote it, so a password in the user information of a reference is *** in every failure that reaches a log or a user.

case UnknownScheme

case UnknownScheme(uri: String, known: List<String>)

The registry has no driver for the scheme of uri; known is what it has.

case NotAddressable

case NotAddressable(uri: String, reason: String)

The driver cannot reach a reference of this form: a file: URI with a query, another driver's scheme.

case NotText

case NotText(uri: String, reason: String)

What is stored at uri is not UTF-8, and a String always is.

case Refused

case Refused(uri: String, reason: String)

The driver tried and the store refused, in its own words.

fn show

fn show(): String

One sentence that names the reference and what went wrong with it.

trait Storage

shared trait Storage with Schemes

Bytes at a reference, wherever the scheme reaches: five members every driver writes, and two over them. A driver that cannot do one of them - a store that cannot list - says so in the Result of that member rather than by missing it, so a program holds one type whatever it stores in.

Every member reaches the outside world and answers a Task. A storage has an identity - a connection, a disk, a table in memory - and a writing member changes it while a task waits, so the trait is a shared trait and every driver a shared type.

Examples

fn copied(var storage: Storage, from: Uri, to: Uri): Task<Result<Void, StorageFailure>> {
  const content = storage.read(from).await()?
  storage.write(to, content).await()
}

Storage.registry - one storage over several drivers, by scheme.
Schemes - what a driver says it answers to.

fn read

fn read(uri: Uri): Task<Result<Bytes, StorageFailure>>

The bytes stored at uri.

fn exists

fn exists(uri: Uri): Task<Result<Bool, StorageFailure>>

Whether anything is stored at uri.

fn list

fn list(uri: Uri): Task<Result<List<Uri>, StorageFailure>>

The references directly below uri, sorted.

fn write

var fn write(uri: Uri, content: Bytes): Task<Result<Void, StorageFailure>>

Stores content at uri, replacing whatever was there - whole or not at all, where the store can promise it.

fn delete

var fn delete(uri: Uri): Task<Result<Void, StorageFailure>>

Removes whatever is stored at uri, and everything below it.

fn readText

fn readText(uri: Uri): Task<Result<String, StorageFailure>>

The bytes read as UTF-8, which is the ninety-percent call.

fn writeText

var fn writeText(uri: Uri, text: String): Task<Result<Void, StorageFailure>>

text stored as UTF-8 at uri: Storage.write for text.

fn registry

static fn registry(drivers: List<Storage>): Storage

One storage over drivers, which hands every reference to the driver whose Schemes hold its scheme - and is itself a Storage, so whoever holds it does not know how many drivers are behind it. The program names every driver it can reach, here, and nothing adds itself.

Errors

StorageFailure.UnknownScheme from every member, for a reference whose scheme no driver answers to. It lists the schemes the registry does know.