arachnespace::pheidippides Class Reference

Batch courier for Wikidata/Commons: collects IDs, issues HTTP requests, and returns a merged JSON payload. More...

#include <include/pheidippides.hpp>

Collaboration diagram for arachnespace::pheidippides:

Public Member Functions
nlohmann::json	fetch_json (const std::unordered_set< std::string > &batch, corespace::entity_kind kind=corespace::entity_kind::any)
	Fetch metadata for a set of entity IDs and return a merged JSON object.
nlohmann::json	sparql (const corespace::sparql_request &request)
	Execute a SPARQL query according to the provided request.
nlohmann::json	wdqs (std::string query)
	Convenience wrapper to run a raw SPARQL query string.
const corespace::network_metrics &	metrics_info () const
	Access aggregated network metrics of the underlying client.
corespace::call_preview	preview (const corespace::sparql_request &request) const
	Produce a call preview describing the HTTP request that would be made.

Static Public Member Functions
static std::string	join_str (std::span< const std::string > ids, std::string_view separator="|")
	Join a span of strings with a separator (no encoding or validation).

Private Member Functions
corespace::call_preview	build_call_preview (const corespace::sparql_request &request) const

Private Attributes
corespace::options	opt {}
	Request shaping parameters (chunking, fields, base params).
corespace::http_client	client {}
	Reused HTTP client (not thread-safe across threads).
corespace::wdqs_options	wdqs_opt {}

Detailed Description

Batch courier for Wikidata/Commons: collects IDs, issues HTTP requests, and returns a merged JSON payload.

Responsibilities:

• Pick the endpoint based on entity kind:
  • Q/P/L/E -> https://www.wikidata.org/w/api.php
  • M (mediainfo) -> https://commons.wikimedia.org/w/api.php
• Build request parameters:
  • for E (EntitySchema): action=query, titles=EntitySchema:<id>, prop=<joined opt.prop>
  • for others: action=wbgetentities, ids=<id>|<id>..., props=<joined opt.props>
• Split the input set into chunks up to batch_threshold.
• Filter IDs by expected kind using arachne::identify(id).
• Merge per-chunk JSON responses using merge_patch.

Thread-safety:

• Not thread-safe; the instance owns a reusable http_client (single easy handle). Use one instance per calling thread.

Note

The implementation currently issues requests even when a chunk becomes empty after filtering (for example when kind == entity_kind::any). The server response for an empty identifier list is merged as-is.

Definition at line 59 of file pheidippides.hpp.

Member Function Documentation

build_call_preview()

corespace::call_preview arachnespace::pheidippides::build_call_preview ( const corespace::sparql_request & request ) const

private

Definition at line 143 of file pheidippides.cpp.

        {
    using namespace corespace;
 
    call_preview preview;
    const auto& profile = get_service_profile(service_kind::wdqs);
    preview.url = profile.base_url;
 
    const std::size_t threshold
        = request.length_threshold == sparql_request::service_default
        ? wdqs_opt.length_threshold
        : request.length_threshold;
 
    const auto method = choose_http_method(request, threshold);
    preview.method = method;
 
    preview.timeout_sec
        = request.timeout_sec >= 0 ? request.timeout_sec : wdqs_opt.timeout_sec;
 
    preview.accept = resolve_accept(request, profile, wdqs_opt.accept_override);
 
    if (method == http_method::get) {
        preview.query_params.emplace_back("query", request.query);
        append_common_params(service_kind::wdqs, method, preview.query_params);
    } else {
        const auto [content_type, use_form_body]
            = resolve_body_strategy(request);
 
        preview.content_type = content_type;
        preview.use_form_body = use_form_body;
        if (preview.use_form_body) {
            preview.form_params.emplace_back("query", request.query);
            sort_parameters(preview.form_params);
        } else {
            preview.body = request.query;
        }
        append_common_params(service_kind::wdqs, method, preview.query_params);
    }
 
    return preview;
}

References corespace::service_profile::base_url, corespace::call_preview::body, corespace::choose_http_method(), corespace::call_preview::content_type, corespace::get, corespace::get_service_profile(), corespace::wdqs_options::length_threshold, corespace::call_preview::method, corespace::sparql_request::query, corespace::call_preview::timeout_sec, corespace::sparql_request::timeout_sec, corespace::wdqs_options::timeout_sec, corespace::call_preview::url, corespace::call_preview::use_form_body, corespace::wdqs, and wdqs_opt.

Referenced by preview(), and sparql().

Here is the call graph for this function:

Here is the caller graph for this function:

fetch_json()

nlohmann::json arachnespace::pheidippides::fetch_json	(	const std::unordered_set< std::string > &	batch,
		corespace::entity_kind	kind = corespace::entity_kind::any )

Fetch metadata for a set of entity IDs and return a merged JSON object.

Behavior:

• Empty batch results in an empty JSON object.
• For kind == entity_kind::entity_schema, IDs are prefixed with EntitySchema: and fields come from opt.prop.
• For other kinds, fields come from opt.props.
• Only elements where arachne::identify(id) == kind are included in a request chunk; if the filter removes every element the request still executes with an empty identifier list and the response is merged.
• Chunk responses are merged into a single object via merge_patch.

Errors:

• Transport or HTTP errors are handled by the internal http_client retry policy; terminal failures throw std::runtime_error.
• Invalid JSON payloads propagate nlohmann::json::parse_error from nlohmann::json::parse.

Parameters

batch	Set of full IDs (e.g., "Q123", "L7-F1", "E42").
kind	Target entity kind (selects API, fields, and filtering).

Returns

Merged JSON object with fetched data.

Definition at line 29 of file pheidippides.cpp.

  {
    if (batch.empty()) {
        return nlohmann::json::object();
    }
    std::string url
        = (kind != corespace::entity_kind::mediainfo
               ? "https://www.wikidata.org/w/api.php"
               : "https://commons.wikimedia.org/w/api.php");
    std::string props
        = (kind != corespace::entity_kind::entity_schema ? join_str(opt.props)
                                                         : join_str(opt.prop));
 
    corespace::parameter_list base_params { opt.params };
    if (kind == corespace::entity_kind::entity_schema) {
        base_params.emplace_back("action", "query");
    } else {
        base_params.emplace_back("action", "wbgetentities");
    }
 
    std::string prefix {};
    if (kind == corespace::entity_kind::entity_schema) {
        prefix = "EntitySchema:";
    }
    nlohmann::json combined = nlohmann::json::object();
    for (auto&& chunk : batch | std::views::chunk(opt.batch_threshold)) {
        std::vector<std::string> chunk_vec;
        for (const auto& id : chunk) {
            if (arachne::identify(id) != kind) {
                continue;
            }
            chunk_vec.emplace_back(prefix + id);
        }
        corespace::parameter_list params { base_params };
        auto entities = join_str(chunk_vec);
 
        if (kind == corespace::entity_kind::entity_schema) {
            params.emplace_back("titles", entities);
            params.emplace_back("prop", props);
        } else {
            params.emplace_back("ids", entities);
            params.emplace_back("props", props);
        }
        auto r = client.get(url, params);
        auto data = nlohmann::json::parse(r.text, nullptr, true);
        if (!data.is_object()) {
            continue;
        }
        combined.merge_patch(data);
    }
    return combined;
}

References corespace::entity_schema, and corespace::mediainfo.

join_str()

std::string arachnespace::pheidippides::join_str ( std::span< const std::string > ids, std::string_view separator = "|" )

static

Join a span of strings with a separator (no encoding or validation).

Edge cases:

• Empty input yields an empty string.
• Separator defaults to "|" (useful for MediaWiki multi-ID parameters).

Parameters

ids	Input strings to join.
separator	Separator between elements (default: "|").

Returns

Concatenated string.

Definition at line 128 of file pheidippides.cpp.

  {
    if (ids.empty()) {
        return {};
    }
    auto it = ids.begin();
    std::string result = *it;
    for (++it; it != ids.end(); ++it) {
        result.append(separator);
        result.append(*it);
    }
    return result;
}

metrics_info()

const corespace::network_metrics & arachnespace::pheidippides::metrics_info ( ) const

nodiscard

Access aggregated network metrics of the underlying client.

Returns

Const reference to metrics snapshot.

Definition at line 119 of file pheidippides.cpp.

                                                                 {
    return client.metrics_info();
}

preview()

corespace::call_preview arachnespace::pheidippides::preview ( const corespace::sparql_request & request ) const

nodiscard

Produce a call preview describing the HTTP request that would be made.

The returned call_preview contains all information necessary to perform the request without actually executing it: resolved URL, HTTP method, query/form parameters, content type/body, Accept header, timeout, and whether the body should be sent as form data.

Parameters

request

SPARQL request used to compute the preview.

Returns

A filled corespace::call_preview describing the planned call.

Definition at line 124 of file pheidippides.cpp.

                                                                  {
    return build_call_preview(request);
}

References build_call_preview().

Here is the call graph for this function:

sparql()

nlohmann::json arachnespace::pheidippides::sparql

(

const corespace::sparql_request &

request

)

Execute a SPARQL query according to the provided request.

Builds the HTTP call preview from request, issues the HTTP call via the internal http_client and parses the returned payload as JSON.

Errors:

• Transport or HTTP failures propagate from the internal http_client (may throw std::runtime_error on terminal failure).
• Malformed JSON in the response propagates nlohmann::json::parse_error.

Parameters

request

Structured SPARQL request (query text, method hint, accept/content-type overrides, timeout, etc.).

Returns

Parsed JSON object containing the service response.

Definition at line 84 of file pheidippides.cpp.

                                                                        {
    const auto
        [method, url, query_params, form_params, body, content_type, accept,
         timeout_sec, use_form_body]
        = build_call_preview(request);
    if (method == corespace::http_method::get) {
        return nlohmann::json::parse(
            client.get(url, query_params, accept, timeout_sec).text, nullptr,
            true
        );
    }
    if (use_form_body) {
        return nlohmann::json::parse(
            client
                .post_form(url, form_params, query_params, accept, timeout_sec)
                .text,
            nullptr, true
        );
    }
    return nlohmann::json::parse(
        client
            .post_raw(
                url, body, content_type, query_params, accept, timeout_sec
            )
            .text,
        nullptr, true
    );
}

References build_call_preview(), and corespace::get.

Here is the call graph for this function:

wdqs()

nlohmann::json arachnespace::pheidippides::wdqs

(

std::string

query

)

Convenience wrapper to run a raw SPARQL query string.

Constructs a default sparql_request with the provided query and forwards to sparql().

Parameters

query

SPARQL query string to execute.

Returns

Parsed JSON object containing the service response.

Definition at line 113 of file pheidippides.cpp.

                                               {
    corespace::sparql_request request;
    request.query = std::move(query);
    return sparql(request);
}

References corespace::sparql_request::query.

Member Data Documentation

client

corespace::http_client arachnespace::pheidippides::client {}

private

Reused HTTP client (not thread-safe across threads).

Definition at line 161 of file pheidippides.hpp.

{}; 

opt

corespace::options arachnespace::pheidippides::opt {}

private

Request shaping parameters (chunking, fields, base params).

Definition at line 159 of file pheidippides.hpp.

{}; 

wdqs_opt

corespace::wdqs_options arachnespace::pheidippides::wdqs_opt {}

private

Definition at line 162 of file pheidippides.hpp.

{};

Referenced by build_call_preview().

---

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

• pheidippides.hpp
• pheidippides.cpp