#include <include/pheidippides/transport.hpp>

Public Member Functions
	transport (std::filesystem::path artifact_root)
const std::filesystem::path &	artifact_root () const noexcept
acquired_artifact_v1	execute (const fetch_request_v1 &request) const
acquired_artifact_v1	execute (const nlohmann::json &request_contract) const

Private Attributes
std::filesystem::path	artifact_root_

Detailed Description

Intentionally blind HTTP transport.

The transport never parses response content. It streams a final response to a staging file, hashes it while writing, and publishes it without replacing an existing artifact.

Definition at line 159 of file transport.hpp.

Constructor & Destructor Documentation

◆ transport()

arachne::pheidippides::transport::transport ( std::filesystem::path artifact_root )

explicit

Definition at line 1569 of file transport.cpp.

                                                    {
    initialize_curl();
    if (artifact_root.empty()) {
        throw std::invalid_argument("artifact root must not be empty");
    }
    std::error_code ec;
    std::filesystem::create_directories(artifact_root, ec);
    if (ec) {
        throw std::system_error(ec, "cannot create artifact root");
    }
    artifact_root_ = std::filesystem::canonical(artifact_root, ec);
    if (ec || !std::filesystem::is_directory(artifact_root_)) {
        throw std::system_error(
            ec ? ec : std::make_error_code(std::errc::not_a_directory),
            "artifact root is not a directory"
        );
    }
}

References arachne::pheidippides::anonymous_namespace{transport.cpp}::initialize_curl().

Here is the call graph for this function:

Member Function Documentation

◆ artifact_root()

const std::filesystem::path & arachne::pheidippides::transport::artifact_root ( ) const

inlinenodiscardnoexcept

Definition at line 163 of file transport.hpp.

                                                                          {
        return artifact_root_;
    }

◆ execute() [1/2]

acquired_artifact_v1 arachne::pheidippides::transport::execute ( const fetch_request_v1 & request ) const

nodiscard

Definition at line 1588 of file transport.cpp.

                                                                             {
    acquired_artifact_v1 result;
    result.artifact_id = "artifact-invalid";
    result.request_id = request.request_id;
    result.door_id = request.door_id;
    result.operation = request.operation;
    result.delivered_via
        = request.operation == transport_operation::resume_download
        ? delivery_mode::resumed
        : delivery_mode::fetched;
    result.source_url = request.url;
    result.started_at = std::chrono::system_clock::now();
 
    if (request.contract != "fetch_request_v1"
        || request.format_version != 1U) {
        return fail_result(
            std::move(result), transport_status::invalid_request,
            "unsupported fetch request format version"
        );
    }
    if (!valid_request_id(request.request_id)) {
        return fail_result(
            std::move(result), transport_status::invalid_request,
            "request_id is not a supported stable identifier"
        );
    }
    result.artifact_id = artifact_id_for(request.request_id);
    if (request.timeout.count() <= 0 || request.connect_timeout.count() <= 0
        || request.read_timeout.count() <= 0
        || request.write_timeout.count() <= 0 || request.max_bytes == 0U) {
        return fail_result(
            std::move(result), transport_status::invalid_request,
            "timeouts and max_bytes must be positive"
        );
    }
    if (request.initial_retry_delay.count() < 0
        || request.maximum_retry_delay.count() < 0
        || request.total_retry_delay_budget.count() < 0
        || request.initial_retry_delay > request.maximum_retry_delay) {
        return fail_result(
            std::move(result), transport_status::invalid_request,
            "retry delays are negative or internally inconsistent"
        );
    }
    if (request.maximum_attempts == 0U
        || request.maximum_attempts > maximum_transport_attempts) {
        return fail_result(
            std::move(result), transport_status::invalid_request,
            "maximum_attempts must be between one and twenty"
        );
    }
    if (request.redirects.maximum_redirects > maximum_redirects
        || (!request.redirects.follow
            && request.redirects.maximum_redirects != 0U)) {
        return fail_result(
            std::move(result), transport_status::invalid_request,
            "redirect limit is inconsistent or exceeds the safety maximum"
        );
    }
    if (request.method == http_method::get
        && (!request.body.empty() || request.body_artifact)) {
        return fail_result(
            std::move(result), transport_status::invalid_request,
            "GET requests cannot contain a body"
        );
    }
    if (!request.body.empty() && request.body_artifact) {
        return fail_result(
            std::move(result), transport_status::invalid_request,
            "request cannot contain both inline and artifact body bytes"
        );
    }
    if ((request.operation == transport_operation::resume_download)
        != request.resume_artifact.has_value()) {
        return fail_result(
            std::move(result), transport_status::invalid_request,
            "resume_download requires exactly one resume_artifact"
        );
    }
    if (request.resume_artifact
        && (request.method != http_method::get
            || request.resume_artifact->byte_length == 0U
            || request.resume_artifact->byte_length >= request.max_bytes
            || request.resume_artifact->storage_ref
                == request.target_artifact_ref)) {
        return fail_result(
            std::move(result), transport_status::invalid_request,
            "resume artifact, method, target, or size is inconsistent"
        );
    }
    if (request.body.size()
        > static_cast<std::size_t>(std::numeric_limits<curl_off_t>::max())) {
        return fail_result(
            std::move(result), transport_status::invalid_request,
            "inline request body is too large for this transport build"
        );
    }
    if (!std::ranges::all_of(request.headers, valid_header)) {
        return fail_result(
            std::move(result), transport_status::invalid_request,
            "request contains an invalid HTTP header"
        );
    }
    if (!crypto::is_safe_relative_artifact_ref(request.target_artifact_ref)) {
        return fail_result(
            std::move(result), transport_status::unsafe_artifact_ref,
            "target artifact reference is not a safe relative path"
        );
    }
 
    std::string validation_error;
    auto current = parse_url(request.url, validation_error);
    if (!current) {
        return fail_result(
            std::move(result), transport_status::invalid_request,
            std::move(validation_error)
        );
    }
    if (!host_allowed(
            *current, request.redirects.allowed_hosts, validation_error
        )) {
        return fail_result(
            std::move(result), transport_status::disallowed_host,
            std::move(validation_error)
        );
    }
 
    std::optional<verified_body_file> body_file;
    if (request.body_artifact) {
        transport_status body_status = transport_status::storage_error;
        body_file = verified_body_file::open_and_verify(
            artifact_root_, *request.body_artifact, body_status,
            validation_error
        );
        if (!body_file) {
            return fail_result(
                std::move(result), body_status, std::move(validation_error)
            );
        }
    }
    std::optional<verified_body_file> resume_file;
    if (request.resume_artifact) {
        transport_status resume_status = transport_status::storage_error;
        resume_file = verified_body_file::open_and_verify(
            artifact_root_, *request.resume_artifact, resume_status,
            validation_error
        );
        if (!resume_file) {
            return fail_result(
                std::move(result), resume_status, std::move(validation_error)
            );
        }
    }
 
    const std::filesystem::path target = crypto::safe_artifact_path(
        artifact_root_, request.target_artifact_ref
    );
    if (!ensure_safe_parent(artifact_root_, target, validation_error)) {
        return fail_result(
            std::move(result), transport_status::storage_error,
            std::move(validation_error)
        );
    }
    std::error_code ec;
    const auto target_state = std::filesystem::symlink_status(target, ec);
    if ((!ec && std::filesystem::exists(target_state))
        || ec == std::errc::too_many_symbolic_link_levels) {
        return fail_result(
            std::move(result), transport_status::artifact_exists,
            "target artifact already exists"
        );
    }
    if (ec && ec != std::errc::no_such_file_or_directory) {
        return fail_result(
            std::move(result), transport_status::storage_error,
            "cannot inspect target artifact: " + ec.message()
        );
    }
 
    std::optional<staging_file> staging;
    try {
        staging.emplace(target.parent_path());
    } catch (const std::exception& exception) {
        return fail_result(
            std::move(result), transport_status::storage_error, exception.what()
        );
    }
 
    easy_handle handle(curl_easy_init());
    if (!handle) {
        return fail_result(
            std::move(result), transport_status::network_error,
            "curl_easy_init failed"
        );
    }
 
    header_list request_headers;
    try {
        request_headers = build_request_headers(request.headers);
    } catch (const std::exception& exception) {
        return fail_result(
            std::move(result), transport_status::invalid_request,
            exception.what()
        );
    }
 
    receive_context received(staging->descriptor(), request.max_bytes);
    progress_context progress {
        .read_timeout = request.read_timeout,
        .write_timeout = request.write_timeout,
        .upload_expected = request.method == http_method::post
            && (!request.body.empty()
                || (body_file && body_file->length() != 0U)),
    };
    progress.reset();
    std::array<char, CURL_ERROR_SIZE> curl_error {};
    curl_easy_setopt(handle.get(), CURLOPT_ERRORBUFFER, curl_error.data());
    curl_easy_setopt(handle.get(), CURLOPT_NOSIGNAL, 1L);
    curl_easy_setopt(handle.get(), CURLOPT_SHARE, curl_connection_share);
    curl_easy_setopt(handle.get(), CURLOPT_MAXCONNECTS, 64L);
    curl_easy_setopt(handle.get(), CURLOPT_FOLLOWLOCATION, 0L);
    curl_easy_setopt(handle.get(), CURLOPT_NOPROGRESS, 0L);
    curl_easy_setopt(
        handle.get(), CURLOPT_XFERINFOFUNCTION, transfer_progress_callback
    );
    curl_easy_setopt(handle.get(), CURLOPT_XFERINFODATA, &progress);
    curl_easy_setopt(handle.get(), CURLOPT_PROTOCOLS_STR, "http,https");
    curl_easy_setopt(handle.get(), CURLOPT_REDIR_PROTOCOLS_STR, "http,https");
    curl_easy_setopt(handle.get(), CURLOPT_HTTP_CONTENT_DECODING, 0L);
    curl_easy_setopt(handle.get(), CURLOPT_FAILONERROR, 0L);
    curl_easy_setopt(
        handle.get(), CURLOPT_CONNECTTIMEOUT_MS,
        static_cast<long>(std::min<std::int64_t>(
            request.connect_timeout.count(), std::numeric_limits<long>::max()
        ))
    );
    curl_easy_setopt(handle.get(), CURLOPT_WRITEFUNCTION, body_callback);
    curl_easy_setopt(handle.get(), CURLOPT_WRITEDATA, &received);
    curl_easy_setopt(
        handle.get(), CURLOPT_HEADERFUNCTION, response_header_callback
    );
    curl_easy_setopt(handle.get(), CURLOPT_HEADERDATA, &received);
    curl_easy_setopt(
        handle.get(), CURLOPT_MAXFILESIZE_LARGE,
        static_cast<curl_off_t>(std::min<std::uint64_t>(
            request.max_bytes,
            static_cast<std::uint64_t>(std::numeric_limits<curl_off_t>::max())
        ))
    );
    if (request_headers) {
        curl_easy_setopt(
            handle.get(), CURLOPT_HTTPHEADER, request_headers.get()
        );
    }
    if (request.method == http_method::post) {
        curl_easy_setopt(handle.get(), CURLOPT_POST, 1L);
        if (body_file) {
            curl_easy_setopt(
                handle.get(), CURLOPT_READFUNCTION, body_read_callback
            );
            curl_easy_setopt(handle.get(), CURLOPT_READDATA, &*body_file);
            curl_easy_setopt(
                handle.get(), CURLOPT_SEEKFUNCTION, body_seek_callback
            );
            curl_easy_setopt(handle.get(), CURLOPT_SEEKDATA, &*body_file);
            curl_easy_setopt(
                handle.get(), CURLOPT_POSTFIELDSIZE_LARGE,
                static_cast<curl_off_t>(body_file->length())
            );
        } else {
            curl_easy_setopt(
                handle.get(), CURLOPT_POSTFIELDS, request.body.data()
            );
            curl_easy_setopt(
                handle.get(), CURLOPT_POSTFIELDSIZE_LARGE,
                static_cast<curl_off_t>(request.body.size())
            );
        }
    } else {
        curl_easy_setopt(handle.get(), CURLOPT_HTTPGET, 1L);
    }
    if (resume_file) {
        curl_easy_setopt(
            handle.get(), CURLOPT_RESUME_FROM_LARGE,
            static_cast<curl_off_t>(resume_file->length())
        );
    }
 
    const auto deadline = std::chrono::steady_clock::now() + request.timeout;
    const parsed_url initial_url = *current;
    bool transfer_completed = false;
    std::chrono::milliseconds retry_delay_spent { 0 };
    auto prepare_staging = [&]() -> bool {
        if (!staging->reset(validation_error)) {
            return false;
        }
        received.reset();
        if (!resume_file) {
            return true;
        }
        if (!resume_file->rewind(validation_error)) {
            return false;
        }
        std::array<char, 64U * 1024U> buffer {};
        for (;;) {
            const std::size_t count
                = resume_file->read(buffer.data(), buffer.size());
            if (resume_file->read_failed()) {
                validation_error = resume_file->read_error();
                return false;
            }
            if (count == 0U) {
                break;
            }
            if (count > received.max_bytes
                || received.byte_count > received.max_bytes - count
                || !write_all(
                    staging->descriptor(), buffer.data(), count,
                    validation_error
                )) {
                if (validation_error.empty()) {
                    validation_error = "resume artifact exceeds max_bytes";
                }
                return false;
            }
            received.hasher.update(
                std::as_bytes(std::span(buffer.data(), count))
            );
            received.byte_count += static_cast<std::uint64_t>(count);
        }
        return true;
    };
    for (std::size_t attempt = 1;
         attempt <= request.maximum_attempts && !transfer_completed;
         ++attempt) {
        result.attempts = attempt;
        current = initial_url;
        result.redirect_chain.clear();
        std::size_t redirect_count = 0;
        if (!prepare_staging()) {
            return fail_result(
                std::move(result), transport_status::storage_error,
                std::move(validation_error)
            );
        }
 
        for (;;) {
            const long remaining = timeout_milliseconds(deadline);
            if (remaining <= 0) {
                return fail_result(
                    std::move(result), transport_status::timed_out,
                    "transport deadline expired"
                );
            }
            curl_easy_setopt(handle.get(), CURLOPT_TIMEOUT_MS, remaining);
            if (body_file) {
                std::string rewind_error;
                if (!body_file->rewind(rewind_error)) {
                    return fail_result(
                        std::move(result), transport_status::storage_error,
                        std::move(rewind_error)
                    );
                }
            }
            curl_easy_setopt(
                handle.get(), CURLOPT_URL, current->normalized_url.c_str()
            );
            progress.reset();
            curl_error.fill('\0');
            const CURLcode curl_status = curl_easy_perform(handle.get());
 
            char* effective_raw = nullptr;
            curl_easy_getinfo(
                handle.get(), CURLINFO_EFFECTIVE_URL, &effective_raw
            );
            result.effective_url = effective_raw == nullptr
                ? current->normalized_url
                : std::string(effective_raw);
            curl_easy_getinfo(
                handle.get(), CURLINFO_RESPONSE_CODE, &result.http_status
            );
            result.response_headers = received.headers;
            result.byte_count = received.byte_count;
 
            if (received.too_large || curl_status == CURLE_FILESIZE_EXCEEDED) {
                return fail_result(
                    std::move(result), transport_status::response_too_large,
                    "response exceeded max_bytes"
                );
            }
            if (received.headers_too_large) {
                return fail_result(
                    std::move(result), transport_status::response_too_large,
                    "response headers exceeded the safety limit"
                );
            }
            if (received.write_failed) {
                return fail_result(
                    std::move(result), transport_status::storage_error,
                    std::move(received.write_error)
                );
            }
            if (body_file && body_file->read_failed()) {
                return fail_result(
                    std::move(result), transport_status::storage_error,
                    body_file->read_error()
                );
            }
            if (curl_status != CURLE_OK) {
                const transport_status status
                    = curl_status == CURLE_OPERATION_TIMEDOUT
                        || progress.read_timed_out || progress.write_timed_out
                    ? transport_status::timed_out
                    : transport_status::network_error;
                const std::string message = progress.read_timed_out
                    ? "transport read-progress timeout expired"
                    : progress.write_timed_out
                    ? "transport write-progress timeout expired"
                    : curl_error.front() == '\0'
                    ? curl_easy_strerror(curl_status)
                    : curl_error.data();
                const bool may_retry = is_retryable_curl_status(curl_status)
                    && attempt < request.maximum_attempts
                    && timeout_milliseconds(deadline) > 0;
                if (may_retry) {
                    const auto delay = retry_delay(request, attempt, {});
                    if (retry_delay_spent + delay
                        > request.total_retry_delay_budget) {
                        return fail_result(
                            std::move(result),
                            transport_status::retry_budget_exhausted,
                            "network retry delay budget was exhausted"
                        );
                    }
                    if (delay.count() >= timeout_milliseconds(deadline)) {
                        return fail_result(
                            std::move(result), transport_status::timed_out,
                            "transport deadline would expire during retry delay"
                        );
                    }
                    retry_delay_spent += delay;
                    std::this_thread::sleep_for(delay);
                    break;
                }
                return fail_result(std::move(result), status, message);
            }
 
            if (is_redirect_status(result.http_status)
                && !received.location.empty()) {
                if (!request.redirects.follow) {
                    return fail_result(
                        std::move(result), transport_status::redirect_rejected,
                        "response attempted a redirect while redirects are "
                        "disabled"
                    );
                }
                if (redirect_count >= request.redirects.maximum_redirects) {
                    return fail_result(
                        std::move(result),
                        transport_status::redirect_limit_exceeded,
                        "response exceeded the configured redirect limit"
                    );
                }
 
                std::string redirect_error;
                auto redirected_url = resolve_redirect(
                    result.effective_url, received.location, redirect_error
                );
                auto redirected = redirected_url
                    ? parse_url(*redirected_url, redirect_error)
                    : std::nullopt;
                if (!redirected) {
                    return fail_result(
                        std::move(result), transport_status::redirect_rejected,
                        std::move(redirect_error)
                    );
                }
                if (current->scheme == "https" && redirected->scheme == "http"
                    && !request.redirects.allow_https_to_http) {
                    return fail_result(
                        std::move(result), transport_status::redirect_rejected,
                        "HTTPS-to-HTTP redirect is prohibited"
                    );
                }
                if (!host_allowed(
                        *redirected, request.redirects.allowed_hosts,
                        redirect_error
                    )) {
                    return fail_result(
                        std::move(result), transport_status::disallowed_host,
                        std::move(redirect_error)
                    );
                }
                result.redirect_chain.emplace_back(redirected->normalized_url);
                current = std::move(redirected);
                ++redirect_count;
                if (!prepare_staging()) {
                    return fail_result(
                        std::move(result), transport_status::storage_error,
                        std::move(validation_error)
                    );
                }
                continue;
            }
            if (resume_file && result.http_status != 206) {
                return fail_result(
                    std::move(result), transport_status::network_error,
                    "provider did not honor the resumable byte-range request"
                );
            }
            result.retry_after = retry_after_delay(received.headers);
            if (is_retryable_status(result.http_status)
                && attempt < request.maximum_attempts) {
                const auto delay
                    = retry_delay(request, attempt, received.headers);
                if (retry_delay_spent + delay
                    > request.total_retry_delay_budget) {
                    return fail_result(
                        std::move(result),
                        transport_status::retry_budget_exhausted,
                        "HTTP retry delay budget was exhausted"
                    );
                }
                if (delay.count() >= timeout_milliseconds(deadline)) {
                    return fail_result(
                        std::move(result), transport_status::timed_out,
                        "transport deadline would expire during retry delay"
                    );
                }
                retry_delay_spent += delay;
                std::this_thread::sleep_for(delay);
                break;
            }
            transfer_completed = true;
            break;
        }
    }
 
    std::string synchronize_error;
    if (!staging->synchronize(synchronize_error)) {
        return fail_result(
            std::move(result), transport_status::storage_error,
            std::move(synchronize_error)
        );
    }
    const std::string digest = received.hasher.finish_hex();
    if (request.expected_sha256 && digest != *request.expected_sha256) {
        return fail_result(
            std::move(result), transport_status::checksum_mismatch,
            "delivered bytes do not match expected SHA-256"
        );
    }
    staging->close();
 
    ec.clear();
    std::filesystem::create_hard_link(staging->path(), target, ec);
    if (ec) {
        const transport_status status = ec == std::errc::file_exists
            ? transport_status::artifact_exists
            : transport_status::storage_error;
        return fail_result(
            std::move(result), status,
            "cannot atomically publish artifact: " + ec.message()
        );
    }
    ec.clear();
    std::filesystem::remove(staging->path(), ec);
    if (!ec) {
        staging->forget();
    }
 
    result.status = transport_status::delivered;
    result.artifact_ref = request.target_artifact_ref;
    result.sha256 = digest;
    result.byte_count = received.byte_count;
    result.error_message.clear();
    result.completed_at = std::chrono::system_clock::now();
    return result;
}

Here is the call graph for this function:

◆ execute() [2/2]

acquired_artifact_v1 arachne::pheidippides::transport::execute ( const nlohmann::json & request_contract ) const

nodiscard

Validate a wire contract through the shared contract validator first.

Definition at line 2169 of file transport.cpp.

                                                             {
    return execute(from_contract(request_contract));
}

Member Data Documentation

◆ artifact_root_

std::filesystem::path arachne::pheidippides::transport::artifact_root_

private

Definition at line 175 of file transport.hpp.

The documentation for this class was generated from the following files:

Public Member Functions

Private Attributes