arachne::pheidippides Namespace Reference

Namespaces
namespace	anonymous_namespace{hardened_transport.cpp}
namespace	anonymous_namespace{transport.cpp}

Classes
class	hardened_transport
struct	http_header
struct	redirect_policy
struct	body_artifact_reference
struct	fetch_request_v1
struct	acquired_artifact_v1
class	transport

Enumerations
enum class	http_method { get , post }
enum class	transport_operation {   bulk_snapshot , incremental_harvest , point_lookup , resume_download ,   backend_read , external_write }
enum class	freshness_policy { fresh_required , cache_allowed , stale_allowed , offline_only }
enum class	delivery_mode {   fetched , cache_validated , stale , resumed ,   offline }
enum class	transport_status {   delivered , invalid_request , unsafe_artifact_ref , disallowed_host ,   redirect_rejected , redirect_limit_exceeded , timed_out , response_too_large ,   network_error , storage_error , artifact_exists , door_policy_rejected ,   cache_miss , checksum_mismatch , retry_budget_exhausted , admission_timeout }

Functions
std::string_view	to_string (transport_operation value) noexcept
std::string_view	to_string (freshness_policy value) noexcept
std::string_view	to_string (delivery_mode value) noexcept
fetch_request_v1	from_contract (const nlohmann::json &document)
nlohmann::ordered_json	to_contract (const acquired_artifact_v1 &artifact)

Enumeration Type Documentation

delivery_mode

enum class arachne::pheidippides::delivery_mode

strong

Enumerator
fetched
cache_validated
stale
resumed
offline

Definition at line 30 of file transport.hpp.

                         {
    fetched,
    cache_validated,
    stale,
    resumed,
    offline,
};

freshness_policy

enum class arachne::pheidippides::freshness_policy

strong

Enumerator
fresh_required
cache_allowed
stale_allowed
offline_only

Definition at line 24 of file transport.hpp.

                            {
    fresh_required,
    cache_allowed,
    stale_allowed,
    offline_only,
};

http_method

enum class arachne::pheidippides::http_method

strong

Enumerator
get
post

Definition at line 15 of file transport.hpp.

{ get, post };

transport_operation

enum class arachne::pheidippides::transport_operation

strong

Enumerator
bulk_snapshot
incremental_harvest
point_lookup
resume_download
backend_read
external_write

Definition at line 16 of file transport.hpp.

                               {
    bulk_snapshot,
    incremental_harvest,
    point_lookup,
    resume_download,
    backend_read,
    external_write,
};

transport_status

enum class arachne::pheidippides::transport_status

strong

Enumerator
delivered
invalid_request
unsafe_artifact_ref
disallowed_host
redirect_rejected
redirect_limit_exceeded
timed_out
response_too_large
network_error
storage_error
artifact_exists
door_policy_rejected
cache_miss
checksum_mismatch
retry_budget_exhausted
admission_timeout

Definition at line 97 of file transport.hpp.

                            {
    delivered,
    invalid_request,
    unsafe_artifact_ref,
    disallowed_host,
    redirect_rejected,
    redirect_limit_exceeded,
    timed_out,
    response_too_large,
    network_error,
    storage_error,
    artifact_exists,
    door_policy_rejected,
    cache_miss,
    checksum_mismatch,
    retry_budget_exhausted,
    admission_timeout,
};

Function Documentation

from_contract()

fetch_request_v1 arachne::pheidippides::from_contract ( const nlohmann::json & document )

nodiscard

Validate and decode the canonical JSON boundary contract.

Definition at line 1341 of file transport.cpp.

                                                             {
    using arachnespace::contracts::contract_name;
    const auto validation = arachnespace::contracts::validate(
        contract_name::fetch_request, document
    );
    if (!validation) {
        throw std::invalid_argument(validation_message(validation));
    }
 
    try {
        fetch_request_v1 request;
        request.contract = document.at("contract").get<std::string>();
        request.format_version
            = document.at("format_version").get<std::uint32_t>();
        request.request_id = document.at("request_id").get<std::string>();
        request.door_id = document.value("door_id", std::string {});
        request.endpoint_id = document.value("endpoint_id", std::string {});
        const std::string operation
            = document.value("operation", std::string("point_lookup"));
        if (operation == "bulk_snapshot") {
            request.operation = transport_operation::bulk_snapshot;
        } else if (operation == "incremental_harvest") {
            request.operation = transport_operation::incremental_harvest;
        } else if (operation == "resume_download") {
            request.operation = transport_operation::resume_download;
        } else if (operation == "backend_read") {
            request.operation = transport_operation::backend_read;
        } else if (operation == "external_write") {
            request.operation = transport_operation::external_write;
        }
        const std::string freshness
            = document.value("freshness_policy", std::string("fresh_required"));
        if (freshness == "cache_allowed") {
            request.freshness = freshness_policy::cache_allowed;
        } else if (freshness == "stale_allowed") {
            request.freshness = freshness_policy::stale_allowed;
        } else if (freshness == "offline_only") {
            request.freshness = freshness_policy::offline_only;
        }
        request.idempotency_key
            = document.value("idempotency_key", std::string {});
        request.url = document.at("locator").get<std::string>();
        request.target_artifact_ref
            = document.at("output_ref").get<std::string>();
 
        const std::string method = document.at("method").get<std::string>();
        request.method
            = method == "POST" ? http_method::post : http_method::get;
 
        if (const auto headers = document.find("headers");
            headers != document.end()) {
            for (const auto& [name, value] : headers->items()) {
                request.headers.push_back({ name, value.get<std::string>() });
            }
        }
        if (const auto expected = document.find("expected");
            expected != document.end()) {
            if (const auto maximum_bytes = expected->find("maximum_bytes");
                maximum_bytes != expected->end()) {
                request.max_bytes = maximum_bytes->get<std::uint64_t>();
            }
            if (const auto timeout = expected->find("timeout_ms");
                timeout != expected->end()) {
                request.timeout
                    = std::chrono::milliseconds(timeout->get<std::int64_t>());
            }
            if (const auto timeout = expected->find("connect_timeout_ms");
                timeout != expected->end()) {
                request.connect_timeout
                    = std::chrono::milliseconds(timeout->get<std::int64_t>());
            }
            if (const auto timeout = expected->find("read_timeout_ms");
                timeout != expected->end()) {
                request.read_timeout
                    = std::chrono::milliseconds(timeout->get<std::int64_t>());
            }
            if (const auto timeout = expected->find("write_timeout_ms");
                timeout != expected->end()) {
                request.write_timeout
                    = std::chrono::milliseconds(timeout->get<std::int64_t>());
            }
            if (const auto checksum = expected->find("sha256");
                checksum != expected->end()) {
                request.expected_sha256 = checksum->get<std::string>();
            }
        }
        if (const auto retry = document.find("retry");
            retry != document.end()) {
            if (const auto attempts = retry->find("maximum_attempts");
                attempts != retry->end()) {
                request.maximum_attempts = attempts->get<std::size_t>();
            }
            if (const auto delay = retry->find("initial_delay_ms");
                delay != retry->end()) {
                request.initial_retry_delay
                    = std::chrono::milliseconds(delay->get<std::int64_t>());
            }
            if (const auto delay = retry->find("maximum_delay_ms");
                delay != retry->end()) {
                request.maximum_retry_delay
                    = std::chrono::milliseconds(delay->get<std::int64_t>());
            }
            if (const auto budget = retry->find("total_delay_budget_ms");
                budget != retry->end()) {
                request.total_retry_delay_budget
                    = std::chrono::milliseconds(budget->get<std::int64_t>());
            }
            request.respect_retry_after
                = retry->value("respect_retry_after", true);
        }
        if (const auto policy = document.find("redirect_policy");
            policy != document.end()) {
            request.redirects.follow = policy->at("follow").get<bool>();
            request.redirects.maximum_redirects
                = policy->at("maximum_redirects").get<std::size_t>();
            request.redirects.allow_https_to_http
                = policy->at("allow_https_to_http").get<bool>();
            request.redirects.allowed_hosts
                = policy->at("allowed_hosts").get<std::vector<std::string>>();
        }
        if (const auto artifact = document.find("body_artifact");
            artifact != document.end()) {
            request.body_artifact = body_artifact_reference {
                .storage_ref = artifact->at("storage_ref").get<std::string>(),
                .sha256 = artifact->at("sha256").get<std::string>(),
                .byte_length = artifact->at("byte_length").get<std::uint64_t>(),
            };
        }
        if (const auto artifact = document.find("resume_artifact");
            artifact != document.end()) {
            request.resume_artifact = body_artifact_reference {
                .storage_ref = artifact->at("storage_ref").get<std::string>(),
                .sha256 = artifact->at("sha256").get<std::string>(),
                .byte_length = artifact->at("byte_length").get<std::uint64_t>(),
            };
        }
        return request;
    } catch (const nlohmann::json::exception& exception) {
        throw std::invalid_argument(
            std::string("cannot decode fetch_request_v1: ") + exception.what()
        );
    }
}

References backend_read, bulk_snapshot, cache_allowed, arachne::pheidippides::fetch_request_v1::door_id, arachne::pheidippides::fetch_request_v1::endpoint_id, external_write, arachnespace::contracts::fetch_request, arachne::pheidippides::fetch_request_v1::format_version, arachne::pheidippides::fetch_request_v1::freshness, get, arachne::pheidippides::fetch_request_v1::idempotency_key, incremental_harvest, arachne::pheidippides::fetch_request_v1::max_bytes, arachne::pheidippides::fetch_request_v1::maximum_attempts, arachne::pheidippides::fetch_request_v1::method, offline_only, arachne::pheidippides::fetch_request_v1::operation, post, arachne::pheidippides::fetch_request_v1::request_id, arachne::pheidippides::fetch_request_v1::respect_retry_after, resume_download, stale_allowed, arachne::pheidippides::fetch_request_v1::target_artifact_ref, and arachne::pheidippides::fetch_request_v1::url.

to_contract()

nlohmann::ordered_json arachne::pheidippides::to_contract ( const acquired_artifact_v1 & artifact )

nodiscard

Encode a transport result as the canonical acquired-artifact contract.

Definition at line 1485 of file transport.cpp.

                                                                       {
    using ordered_json = nlohmann::ordered_json;
    ordered_json document = ordered_json::object();
    document["contract"] = "acquired_artifact_v1";
    document["format_version"] = 1;
    document["artifact_id"] = artifact.artifact_id.empty()
        ? artifact_id_for(artifact.request_id)
        : artifact.artifact_id;
    document["request_id"] = artifact.request_id;
    if (!artifact.door_id.empty()) {
        document["door_id"] = artifact.door_id;
    }
    document["operation"] = std::string(to_string(artifact.operation));
    document["source_locator"]
        = receipt_safe_text(redact_url_query(artifact.source_url));
 
    ordered_json transport_metadata = ordered_json::object();
    transport_metadata["status"]
        = artifact.delivered() ? "delivered" : "failed";
    transport_metadata["attempts"] = artifact.attempts;
    transport_metadata["delivery_mode"]
        = std::string(to_string(artifact.delivered_via));
    if (artifact.retry_after) {
        transport_metadata["retry_after_ms"] = artifact.retry_after->count();
    }
    if (!artifact.delivered()) {
        transport_metadata["error_code"]
            = std::string(status_name(artifact.status));
        transport_metadata["error_message"] = artifact.error_message.empty()
            ? "transport failed without additional detail"
            : receipt_safe_text(artifact.error_message);
    }
    document["transport"] = std::move(transport_metadata);
 
    ordered_json response_metadata = ordered_json::object();
    response_metadata["status_code"] = artifact.http_status;
    if (!artifact.effective_url.empty()) {
        response_metadata["effective_url"]
            = receipt_safe_text(redact_url_query(artifact.effective_url));
    }
    response_metadata["headers"] = ordered_json::array();
    for (const auto& header : artifact.response_headers) {
        response_metadata["headers"].push_back(
            { { "name", receipt_safe_text(header.name) },
              { "value",
                sensitive_header_name(header.name)
                    ? "[REDACTED]"
                    : receipt_safe_text(header.value) } }
        );
    }
    response_metadata["redirect_chain"] = ordered_json::array();
    for (const auto& redirect : artifact.redirect_chain) {
        response_metadata["redirect_chain"].push_back(
            receipt_safe_text(redact_url_query(redirect))
        );
    }
    response_metadata["started_at"] = rfc3339(artifact.started_at);
    response_metadata["completed_at"] = rfc3339(artifact.completed_at);
    document["response_metadata"] = std::move(response_metadata);
 
    if (artifact.delivered()) {
        ordered_json artifact_reference = ordered_json::object();
        artifact_reference["storage_ref"] = artifact.artifact_ref;
        artifact_reference["sha256"] = artifact.sha256;
        artifact_reference["byte_length"] = artifact.byte_count;
        if (const auto content_type
            = response_content_type(artifact.response_headers)) {
            artifact_reference["media_type"] = receipt_safe_text(*content_type);
        }
        document["artifact"] = std::move(artifact_reference);
    }
    document["acquired_at"] = rfc3339(artifact.completed_at);
 
    const nlohmann::json validation_document = document;
    const auto validation = arachnespace::contracts::validate(
        arachnespace::contracts::contract_name::acquired_artifact,
        validation_document
    );
    if (!validation) {
        throw std::invalid_argument(validation_message(validation));
    }
    return document;
}

References arachnespace::contracts::acquired_artifact, arachne::pheidippides::acquired_artifact_v1::artifact_ref, arachne::pheidippides::acquired_artifact_v1::attempts, arachne::pheidippides::acquired_artifact_v1::byte_count, arachne::pheidippides::acquired_artifact_v1::delivered(), arachne::pheidippides::acquired_artifact_v1::door_id, arachne::pheidippides::acquired_artifact_v1::effective_url, arachne::pheidippides::acquired_artifact_v1::http_status, arachne::pheidippides::acquired_artifact_v1::request_id, and arachne::pheidippides::acquired_artifact_v1::sha256.

Here is the call graph for this function:

to_string() [1/3]

std::string_view arachne::pheidippides::to_string ( delivery_mode value )

nodiscardnoexcept

Definition at line 1325 of file transport.cpp.

                                                             {
    switch (value) {
    case delivery_mode::fetched:
        return "fetched";
    case delivery_mode::cache_validated:
        return "cache_validated";
    case delivery_mode::stale:
        return "stale";
    case delivery_mode::resumed:
        return "resumed";
    case delivery_mode::offline:
        return "offline";
    }
    return "fetched";
}

References cache_validated, fetched, offline, resumed, and stale.

to_string() [2/3]

std::string_view arachne::pheidippides::to_string ( freshness_policy value )

nodiscardnoexcept

Definition at line 1311 of file transport.cpp.

                                                                {
    switch (value) {
    case freshness_policy::fresh_required:
        return "fresh_required";
    case freshness_policy::cache_allowed:
        return "cache_allowed";
    case freshness_policy::stale_allowed:
        return "stale_allowed";
    case freshness_policy::offline_only:
        return "offline_only";
    }
    return "fresh_required";
}

References cache_allowed, fresh_required, offline_only, and stale_allowed.

to_string() [3/3]

std::string_view arachne::pheidippides::to_string ( transport_operation value )

nodiscardnoexcept

Definition at line 1293 of file transport.cpp.

                                                                   {
    switch (value) {
    case transport_operation::bulk_snapshot:
        return "bulk_snapshot";
    case transport_operation::incremental_harvest:
        return "incremental_harvest";
    case transport_operation::point_lookup:
        return "point_lookup";
    case transport_operation::resume_download:
        return "resume_download";
    case transport_operation::backend_read:
        return "backend_read";
    case transport_operation::external_write:
        return "external_write";
    }
    return "point_lookup";
}

References backend_read, bulk_snapshot, external_write, incremental_harvest, point_lookup, and resume_download.