pub trait AsyncLocate<R>: AsyncBlobEngine<R> {
type Ref<'a>
where Self: 'a;
type Location;
type LocateError: Error + Send + Sync + 'static;
// Required methods
fn locate<'a>(
&'a self,
ctx: Connected<'a, Self::Connection, Self::ReadContext<'a>>,
key: &'a R::Key,
suffix: Option<&str>,
) -> Result<Self::Ref<'a>, Self::LocateError>
where R: Transformer;
fn location<'a>(
&'a self,
reference: Self::Ref<'a>,
) -> Result<Self::Location, Self::LocateError>;
}Expand description
Resolve a blob’s ADDRESS without reading it — the wire-facing ref.
An OPTIONAL capability and a SUPERTRAIT of the AsyncBlobEngine face it extends. Standalone it could
not spell its own Connected<…> parameter — it has no Connection / ReadContext to project —
and a handle typically holds only its slot, the root living on the
Connection, so a handle-only locate could not even render an address.
locate is a PURE address render — NO existence check, and NO ROUND TRIP: the
store renders the address out of what it already holds, which is what lets a caller hand out a
reference having touched nothing, and what keeps this from being a get that throws its bytes
away.
§SYNCHRONOUS on both faces, and the pin is what says so
Neither verb here returns a future, on this face or on Locate, and the pin above is
the reason rather than a mode judgement: a render out of what the store already holds cannot be
waiting for anything. A filesystem joins its root to the key’s segments; an object store
concatenates a prefix, or signs a URL out of credentials it is already carrying. Both are LOCAL
rendering, so an async fn here would be an async fn in name only — which is precisely the
fiction the dual-mode law refuses in the other direction.
That leaves this capability with NO mode difference at all, and the twin below exists anyway for
the sibling law’s own reason: a blocking-only store must reach its Connection and its scopes
through a face it implements, and AsyncBlobEngine is not that face.
§THE LOCATION IS THE BACKEND’S, and the seat that says so is BARE
Location carries NO bound naming a wire library, a serializer or a shape.
The backend defines it — FsLocation { path, size }, S3Location { url, etag, size }, whatever
a store actually knows about where its bytes are — exactly as type Score is the ENGINE’s on the
two search seams. A bound here would make every location the property of whichever library the
bound named, and a second backend could not answer without that library compiled.
Where the form is SPENT is where it is demanded: a wire face returning a location asks it for
ToGraphqlOutput structurally, and a location no binding can render
fails at that face rather than at this seat. It is [ToGraphqlOutput::Output]’s own law, one
layer down, and it is what keeps the ORPHAN RULE out of a backend’s way: the location is the
backend’s LOCAL type, so its crossing row is an ordinary local impl.
BlobLocation is A citizen of that seat and never THE law — the
convenience shape a backend with nothing more to say elects, and the one this crate’s own
filesystem store takes.
§TWO members, because a bare seat has no producer the framework could write
Nothing generic can build a Self::Location — no bound means no constructor, no From, no
conversion this crate could call. So the backend that DEFINES the type is the one that MINTS it,
and location is where. The alternative — a bound supplying the conversion —
is the law this seat exists to refuse.
Required Associated Types§
Sourcetype Ref<'a>
where
Self: 'a
type Ref<'a> where Self: 'a
The backend-chosen address handle — a path for a filesystem, a URL or object name for a remote
store. Backend-CHOSEN for the reason AsyncBlobEngine::Payload is, and hardened to neither.
§Why it takes a lifetime, when every shipped reference owns its bytes
A seat is only as bare as its POSITION, and a non-GAT type Ref is not bare: it says and it
borrows nothing from the connection, which is a constraint on every future backend that
nobody ruled. A store whose address is a slice of a manifest it already holds — an object name
interned in the client’s own table, a prefix owned by the connection-manager — would have to
COPY to answer, and the copy would exist because of this line rather than because of anything
the backend needed.
'a is locate’s own borrow: the handle and the
Connection behind ctx at once, which is the pair a reference could
have come out of. where Self: 'a is the ordinary well-formedness the seat needs to be
projected at that borrow, and a backend with nothing to borrow writes an owned type
(type Ref<'a> = PathBuf) and never spends the parameter — the shipped filesystem store is
exactly that.
Sourcetype Location
type Location
WHERE a blob is, as this backend describes it — the carrier a caller hands on, and the form a wire face returns.
BARE: no bound, for the reason the trait note gives. The ADDRESS inside it renders as text — that is what a client can round-trip — and the structure AROUND the address is the backend’s alone.
Sourcetype LocateError: Error + Send + Sync + 'static
type LocateError: Error + Send + Sync + 'static
The address-resolution failure — a SEPARATE associated type from AsyncBlobEngine::Error, because a
second type Error under the supertrait makes every generic L::Error use E0221-ambiguous.
Send + Sync + 'static so a resolver can surface it as a wire error.
location reports through it too, and deliberately: rendering an address is
the tail of resolving one, and a third type Error would make L::LocateError ambiguous the
way a second one already would.
Required Methods§
Sourcefn locate<'a>(
&'a self,
ctx: Connected<'a, Self::Connection, Self::ReadContext<'a>>,
key: &'a R::Key,
suffix: Option<&str>,
) -> Result<Self::Ref<'a>, Self::LocateError>where
R: Transformer,
fn locate<'a>(
&'a self,
ctx: Connected<'a, Self::Connection, Self::ReadContext<'a>>,
key: &'a R::Key,
suffix: Option<&str>,
) -> Result<Self::Ref<'a>, Self::LocateError>where
R: Transformer,
Resolve the on-store ADDRESS of key’s blob WITHOUT reading it. Its signature projects only
R::Key, so it carries the identity capability alone — the rest of the address is suffix,
which the CALLER decided.
suffix is the tail the address ends with, or None for an extensionless one. It is a
PARAMETER and not a projection off R for AsyncBlobEngine::read’s reason, written out there in
full: a family whose suffix is decided per entry has that value only where the row is, and a
parameter is the only way across this seam. None means extensionless and never ask the
type.
ONE lifetime, over the handle, the connection borrow and the key together — the same choice
Connected itself makes and for the same reason: a reference may come out of any of the
three, so 'a is their intersection, and every one of them is covariant, so a caller holding
them at different lifetimes still passes them here unchanged. suffix is NOT under it: a
backend renders the tail INTO the address it is building rather than borrowing it onward, so
tying it to 'a would demand a caller’s own computed suffix outlive the borrow it was computed
under — which is exactly the shape a per-entry suffix has.
§Errors
LocateError where the address cannot be rendered — a slot, a key or a
suffix the backend will not name a stored object after.
Sourcefn location<'a>(
&'a self,
reference: Self::Ref<'a>,
) -> Result<Self::Location, Self::LocateError>
fn location<'a>( &'a self, reference: Self::Ref<'a>, ) -> Result<Self::Location, Self::LocateError>
Describe a resolved address — the backend’s own Location around it.
INFALLIBLE of I/O, which is locate’s pin carried to its end:
the pair resolves and describes without one round trip between them, so a caller holding a key
hands out a location having touched no store. A backend wanting a fact only the store knows —
a size, an etag — reads it from what it already holds, or leaves it unsaid; it does not go and
ask, because a locate that secretly stats is the get-that-throws-its-bytes-away this
capability exists instead of.
That law is THIS layer’s, and the family seam above it keeps it rather than trading it away.
ArtifactStore::locate answers a wire field whose two lawful
answers are an address and not yet generated, so absence is a value it has to be ABLE to
produce — and which stores can produce it is a fact about them: one holding presence as a row
column answers None for free, where a filesystem would have to spend a stat whose answer
expires as it is produced. The shipped family therefore spends this render to build its address
and answers Some; nothing at either layer goes looking on a caller’s behalf, and absence
under it is discovered at USE — in ArtifactData::read, which
finds it for free, or at the client’s own fetch.
It CONSUMES the reference: a location is what the address becomes, so nothing is left beside it to go out of step.
§Errors
LocateError where the address has no rendering — the filesystem store’s
non-UTF-8 path is the shipped instance.
It takes the reference at the SAME 'a locate minted it under, and it must:
Self::Ref<'x> is only well-formed where Self: 'x, and &'a self is what puts that bound in
scope. A borrowing reference therefore describes itself while the store that lent it is still
there, which is the honest reading of a pure render — nothing is fetched, so nothing outlives
what it was read out of.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".
Implementors§
Source§impl<R> AsyncLocate<R> for LocalFsBlob
The other face, DELEGATED — and here there is no bridge at all, because neither verb ever touched
the disk and neither is wrapped. Both are plain calls onto the face above.
impl<R> AsyncLocate<R> for LocalFsBlob
The other face, DELEGATED — and here there is no bridge at all, because neither verb ever touched the disk and neither is wrapped. Both are plain calls onto the face above.
This is the capability where the two faces became method-identical, and the delegation is what keeps them one body: the address funnel is reached from exactly one place whichever trait a caller’s bound named.