bookclerk_storage::guest
Serving a backend's intent operations from a storage guest.
Serves a StorageBackend's intent operations through a storage guest's
Destination capability.
The local and s3 destination plugins each wrap one backend. The
helpers here turn the plugin ABI's requests into backend calls and the
backend's results into ABI replies, so both guests answer the intent
operations the same way and declare exactly the ones their backend does
natively (see docs/plugins/abi.md#intent-operations).
| Item | Kind | Summary |
|---|---|---|
plugin_error |
function | Maps a storage error onto the plugin error a guest answers with. |
storage_features |
function | The storage.* features to accept in describe for a backend with capabilities: one per operation the backend does natively. |
object_metadata |
function | The ABI metadata for a backend probe. |
write_condition |
function | The write precondition in options, if any. |
list |
function | One listing page, honouring the hints the backend supports. |
move_object |
function | Moves one object. |
move_many |
function | Moves explicit pairs, or one page of a prefix. |
delete_many |
function | Deletes up to MAX_BATCH_KEYS keys, one outcome per key in order. |
head_many |
function | Probes up to MAX_BATCH_KEYS keys, one entry per key in order. |
translate_keys |
function | Translates up to MAX_BATCH_KEYS host keys into the keys the backend stores them under, one per key in order. |
changes |
function | Serves changes from the backend's change feed. |
pub fn plugin_error(err: StorageError) -> PluginError
Maps a storage error onto the plugin error a guest answers with.
A failed precondition is conflict, a malformed key invalidParams, and
a cursor the backend no longer accepts invalidCursor, so the host can
tell them apart from backend failures.
pub fn storage_features(capabilities: StorageCapabilities) -> Vec<String>
The storage.* features to accept in describe for a backend with
capabilities: one per operation the backend does natively.
pub fn object_metadata(probe: ObjectProbe) -> ObjectMetadata
The ABI metadata for a backend probe.
pub fn write_condition(
options: &WriteOptions,
) -> Result<Option<WriteCondition>, PluginError>
The write precondition in options, if any.
Returns PluginError::invalid_params when both ifMatch and
ifNoneMatch are set, or when a precondition is combined with
stageOnly (a staged object is published by commit, which carries no
precondition).
pub async fn list<B: StorageBackend + ?Sized>(
backend: &B,
options: ListOptions,
) -> Result<ListPage, PluginError>
One listing page, honouring the hints the backend supports.
Returns the backend's listing error as a plugin error.
pub async fn move_object<B: StorageBackend + ?Sized>(
backend: &B,
from: &str,
to: &str,
options: MoveOptions,
) -> Result<MoveResult, PluginError>
Moves one object.
Returns the backend's error as a plugin error (conflict for a failed
precondition).
pub async fn move_many<B: StorageBackend + ?Sized>(
backend: &B,
request: MoveManyRequest,
) -> Result<MoveManyPage, PluginError>
Moves explicit pairs, or one page of a prefix.
Pairs ignore ifSourceMatch, which names one object's etag, the same as
the host's fallback does.
Returns PluginError::invalid_params for more than
MAX_BATCH_KEYS pairs, and prefix errors (overlapping prefixes, a
stale cursor, listing failures) as plugin errors. Per-object failures
are in the page.
pub async fn delete_many<B: StorageBackend + ?Sized>(
backend: &B,
keys: Vec<String>,
) -> Result<Vec<KeyOutcome>, PluginError>
Deletes up to MAX_BATCH_KEYS keys, one outcome per key in order.
Returns PluginError::invalid_params for too many keys, and a backend
error that failed the whole batch.
pub async fn head_many<B: StorageBackend + ?Sized>(
backend: &B,
keys: Vec<String>,
) -> Result<Vec<Option<ObjectMetadata>>, PluginError>
Probes up to MAX_BATCH_KEYS keys, one entry per key in order.
Returns PluginError::invalid_params for too many keys, and the first
probe failure other than absence.
pub async fn translate_keys<B: StorageBackend + ?Sized>(
backend: &B,
keys: Vec<String>,
) -> Result<Vec<String>, PluginError>
Translates up to MAX_BATCH_KEYS host keys into the keys the backend
stores them under, one per key in order.
Returns PluginError::invalid_params for too many keys or a key that
breaks the host key syntax (crate::key_syntax::HostKey), and the
backend's failure.
pub async fn changes<B: StorageBackend + ?Sized>(
backend: &B,
request: ChangesRequest,
) -> Result<ChangesPage, PluginError>
Serves changes from the backend's change feed.
A backend without a feed (for the local plugin, an instance with
watch off) answers with an empty page that says changes may have been
missed, so the host lists instead.
Returns invalidCursor for a cursor the feed does not accept, and the
feed's other failures.
Generated from crates/bookclerk-storage at main · View as Markdown