Skip to main content

AsyncLocate

Trait AsyncLocate 

Source
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§

Source

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.

Source

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.

Source

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§

Source

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.

Source

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
where R: LocalFsBlobRecord, R::Bytes: AsRef<[u8]>,

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.