Skip to content
YosoiDocs

Responses

A response contains acquisition attempts in Policy order. Each attempt contains an outcome for each document requested from that acquisition.

Acquisition attempt Requested representation Example outcome
Direct HTTP Response document Produced
Browser Rendered DOM Produced
Browser Accessibility tree Partial

This structure lets you use a successful document while keeping the reasons another document was unavailable.

AttemptState Meaning
Completed The acquisition completed; inspect its document outcomes and HTTP status
Failed(kind) The acquisition failed; diagnostic() may explain why
NotStarted(reason) The acquisition did not start

status() returns Option<u16> because an HTTP response may never have been observed. A completed attempt is not a promise of a successful HTTP status or usable document.

DocumentOutcome Meaning
Produced(document) The requested representation was materialized
Partial { document, reasons } Evidence is incomplete; a usable document may be present
Unavailable(reason) The requested evidence is unavailable
Unprojectable(reason) Captured evidence could not become the requested document

Use document() when you intentionally accept both produced and usable partial documents. Match the enum when completeness affects your result.

This function accepts a response and prints titles from fully produced HTML documents:

use std::error::Error;
use yosoi::prelude as ys;
use ys::documents::DocumentClass;
use ys::request::{DocumentOutcome, ResponseRef};

fn print_titles(response: ResponseRef<'_>) -> Result<(), Box<dyn Error>> {
    let plan = ys::Plan::new([ys::output("title", ys::css("h1")?.text())?])?;

    // callout: A response keeps every acquisition attempt in Policy order. Inspect each attempt's requested documents separately.
    for attempt in response.attempts() {
        for selected in attempt.documents() {
            match selected.outcome() {
                // callout: This branch accepts only fully produced HTML. A completed acquisition alone does not guarantee usable evidence.
                DocumentOutcome::Produced(document)
                    if document.class() == DocumentClass::SourceHtml =>
                {
                    println!("{:?}", document.locate(&plan));
                }
                DocumentOutcome::Partial { reasons, .. } => { // callout: Partial evidence stays distinct. Inspect `reasons` before deciding whether it is sufficient for your task.
                    eprintln!("Partial document: {reasons:?}");
                }
                other => eprintln!("Other document outcome: {other:?}"),
            }
        }
    }
    Ok(())
}

This helper accepts an acquired Response and inspects each requested representation. Partial documents remain distinct from produced HTML.

import yosoi as ys

def print_titles(response):
    plan = ys.Plan(outputs=[ys.output("title", ys.css("h1").text())])
    # callout: A response keeps every acquisition attempt in Policy order. Inspect each attempt's requested documents separately.
    for attempt in response.attempts:
        for selected in attempt.documents:
            outcome = selected.outcome
            # callout: This branch accepts only fully produced HTML. A completed acquisition alone does not guarantee usable evidence.
            if outcome.status == "produced" and outcome.document.document_class == "source_html":
                print(outcome.document.locate(plan))
            elif outcome.status == "partial": # callout: Partial evidence stays distinct. Inspect `reasons` before deciding whether it is sufficient for your task.
                print("Partial document:", outcome.reasons)
            else:
                print("Other document outcome:", outcome)

Pass a Response returned by send to this helper. The fields expose the same per-attempt document outcomes.

Pass response.as_ref() for a normal request or capture.response() for a Map capture.

Response owns the result. ResponseRef, Attempt, AttemptDocument, and DocumentRef borrow from it. Reading a document’s bytes does not copy them.

Call DocumentRef::to_owned() when a document must outlive the response. This retains an owned copy; use it deliberately for larger documents. An owned document can also be passed to a Contract’s generated locate() method. To avoid the copy, call document.locate(MyContract::plan()?) on the borrowed document.

request_id() identifies the request. Each attempt has a capture_id(), requested_target(), acquisition(), and authored_selection(). Each selected document reports requested().

policy_snapshot() preserves the validated Policy used for execution. termination() distinguishes normal completion from cancellation. Keep these facts alongside the data you use when you need to explain an outcome.