Struct Request 

pub struct Request {
    pub basis: Basis,
    pub query: Query,
    pub now: SystemTime,
    /* private fields */
}

Everything that determines an answer.

The three public fields are the answer’s whole input. A private fourth records how the basis’s analyzers were chosen, which no answer reads and only a refusal does, so a request outside this crate is made with Self::new, Self::read, or Self::build rather than a struct literal.

Fields

basis: Basis

Root, scope, and content: what a holder of stored state must match.

query: Query

Selection, views, and view options.

now: SystemTime

The instant relative time windows were resolved against.

Fixed when the request is built, so Selection::modified is absolute and a watch that builds its request once at start never slides its window.

Implementations

impl Request

pub const DEFAULTS: RequestDefaults

The defaults table.

pub const fn new(basis: Basis, query: Query, now: SystemTime) -> Self

One read of what basis holds, from a query its caller already has typed.

The composition six call sites wrote out by hand, each of them a holder’s basis and one read’s query and instant. A literal is not wrong, but a name is where the rule can be stated: basis is the holder’s, never the read’s, and now is this read’s, fixed so a watch that repaints does not slide its own window.

No validation, because the query is already typed and its holder is the one that knows which rule applies – Self::validate_read for a retained index, Self::validate for a request that is its own basis. Self::read is the constructor that parses and validates in one step.

Nothing is implied: the basis is the caller’s, whole. A refusal says what the basis holds (BasisHolder::Supplied) rather than naming an analyzer to add, because no analyzer axis built it.

pub fn implied_by(&self) -> &[ViewSpec]

The named views whose analyzers Self::build added to the basis, in the caller’s order; empty for a basis supplied whole.

Provenance, not part of the answer: the basis’s content already includes what they imply. It is what a watch refusal names (RequestError::WatchContent), since the caller wrote a view rather than an analyzer.

pub fn read( basis: Basis, spec: &ReadSpec<'_>, now: SystemTime, axes: &'static AxisNames, ) -> Result<Self, RequestError>

One read of what basis holds, written in the value grammars.

The constructor every read site wants: a holder supplies the basis it was opened with, and the caller supplies only what this read asks. The view default comes from the analyzers the basis already holds, so a typed set never has to be spelled back into the grammar to find out what a request that read files displays, and no caller builds a request with a throw-away basis and overwrites it afterwards.

A held basis is never widened: a view that implies an analyzer the holder was not opened with is refused (RequestError::ViewNeedsAnalyzer) rather than read for, because a read cannot add to what the holder paid for.

Errors

RequestError for a value no grammar accepts, and for a read the basis cannot answer: Self::validate’s rules, which here are the holder’s own. A refusal for missing analysis names what the index was opened with (BasisHolder::Index), since that is the holder this constructor reads for.

pub fn read_opened( spec: &ReadSpec<'_>, now: SystemTime, axes: &'static AxisNames, ) -> Result<Self, RequestError>

One read of an opened root, written in the value grammars.

Self::read over OpenedIndex::basis, the one statement of what every opened root holds, except that a refusal for missing analysis says an opened root runs no analyzer (BasisHolder::OpenedRoot) rather than naming an analyzer to open it with, which its constructor does not take.

Errors

RequestError as Self::read returns it.

pub fn build( spec: &RequestSpec<'_>, now: SystemTime, axes: &'static AxisNames, ) -> Result<Self, RequestError>

Parse a spec into a request, resolving relative time windows against now.

Refusals name each axis as axes spells it, and so do the report diagnostics of the query built here. Every value is parsed before any is checked against another, in the order the command line reads its flags: content, views, selection, the page denominator, then scope. Rules that relate axes are Self::validate’s.

This request builds its own basis, so a view that shows analysis requests it: the basis enables the analyzers analyze names together with the ones the named views imply (ViewSpec::implies), and full and the default view are resolved against that union. --view code and --analyze code therefore build one basis, and share one sidecar and one answer. Only a view with no metadata meaning implies anything, so no metadata report ever turns into a read of file bodies.

pub fn validate(&self) -> Result<(), RequestError>

Refuse a request no holder of its own basis could answer.

In order: more views than one report carries, a view its content cannot answer, and a selection by ignored state its scope does not observe. A refusal for missing analysis offers the remedy of the constructor that made the request: the analyzer to add for one Self::build made, and what the basis holds for one supplied whole.

pub fn validate_read(&self, held: &Basis) -> Result<(), RequestError>

Refuse a read that held, the basis of a retained index, cannot answer.

Content must be equal: an index built with other analyzers holds other metrics, and serving a narrower request from a wider store is a projection this model does not define. The remaining rules are Self::validate’s, applied to what held observed rather than to what the request says it would have, and a refusal for missing analysis names what the index was opened with. Scope equality is not checked here; ScanConfig owns it.

pub fn validate_delivery(&self, delivery: &Delivery) -> Result<(), RequestError>

Refuse a delivery that cannot carry this request out.

Everything a watch cannot do, in one place, because a watch is the one delivery that changes which requests can be answered at all:

• A narrowed scan scope (RequestError::WatchScope): a watcher cannot filter its backend’s events against a boundary the scan drew. Selection still works, because it filters the retained index rather than the scan.
• Content analysis (RequestError::WatchContent): nothing re-reads a file the watch sees change, so a session would go on reporting the metrics it started with as fresh. Named or implied alike, and the refusal names every axis that enabled it – the analyzers named and the views that implied the rest (Self::implied_by) – since those are what the caller wrote, and dropping only one would not help.
• A snapshot nothing verified (RequestError::WatchCacheOnly): the window between the snapshot and the session’s start is never observed, so the first answer would describe a tree that may have moved and every later one would build on it.

Each was a guard on one surface, which is why a library caller and a Python caller could ask for what the command line refuses.

One refusal applies to every route: a stale answer comes from the snapshot, which CachePolicy::Off never reads (RequestError::StaleOkCacheOff).

Trait Implementations

impl Clone for Request

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Request

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.