corespace Namespace Reference

Namespaces
namespace	anonymous_namespace{http_client.cpp}

Classes
class	http_client
	Minimal, synchronous HTTP GET client built on libcurl. More...
struct	options
	Configuration for fetching entities via MediaWiki/Wikibase API. More...
struct	network_metrics
	Thread-safe counters describing client-side networking activity. More...
struct	http_response
	Result object for an HTTP transfer. More...
struct	network_options
	Fixed runtime options for the HTTP client. More...
struct	sparql_request
struct	service_profile
	Static configuration values describing a remote service. More...
struct	wdqs_options
	Options specific to WDQS usage and heuristics. More...
struct	call_preview

Typedefs
using	parameter = std::pair<std::string, std::string>
	Single query parameter: key=value (pre-encoding is handled by libcurl).
using	parameter_list = std::vector<parameter>
	Ordered list of query parameters appended to the URL.

Enumerations
enum class	interface { command_line , interactive }
enum class	entity_kind {   item , property , lexeme , mediainfo ,   entity_schema , form , sense , any ,   unknown }
	Wikidata entity kind. More...
enum	service_kind { wdqs }
	Identifies supported SPARQL services. More...
enum class	http_method { get , post }
	HTTP method to use for a request. More...
enum class	http_method_hint { automatic , force_get , force_post }
	Hint for selecting the HTTP method for a request. More...

Functions
std::mt19937_64 &	rng ()
	Shared PRNG seeded on first use.
std::string	random_hex (std::size_t n)
	Return exactly n random hexadecimal characters (lowercase).
const service_profile &	wdqs_profile ()
http_method	choose_http_method (const sparql_request &request, std::size_t threshold)
	Chooses the appropriate HTTP method for a SPARQL request.
std::string	resolve_accept (const sparql_request &request, const service_profile &profile, std::string_view override_accept)
	Resolves the Accept header value for a SPARQL request.
std::pair< std::string, bool >	resolve_body_strategy (const sparql_request &request)
	Determines the body content and strategy for a SPARQL request.
const service_profile &	get_service_profile (service_kind kind)
	Retrieve the service profile for a given service kind.
void	sort_parameters (parameter_list &params)
	Sorts the parameter list in-place by key.
void	append_common_params (service_kind kind, http_method method, parameter_list &params)
	Appends common parameters required for a service and HTTP method.

Typedef Documentation

parameter

using corespace::parameter = std::pair<std::string, std::string>

Single query parameter: key=value (pre-encoding is handled by libcurl).

Definition at line 61 of file utils.hpp.

parameter_list

using corespace::parameter_list = std::vector<parameter>

Ordered list of query parameters appended to the URL.

Definition at line 63 of file utils.hpp.

Enumeration Type Documentation

entity_kind

enum class corespace::entity_kind

strong

Wikidata entity kind.

Names include the canonical identifier prefixes for clarity:

• item (IDs such as "Q123"), property ("P45"), lexeme ("L7"), mediainfo ("M9"), entity_schema ("E2"), form ("L7-F1"), sense ("L7-S2"). any acts as an API selector; unknown denotes an invalid or unrecognized identifier.

Enumerator
item	IDs prefixed with 'Q'.
property	IDs prefixed with 'P'.
lexeme	IDs prefixed with 'L'.
mediainfo	IDs prefixed with 'M'.
entity_schema	IDs prefixed with 'E'.
form	Lexeme form IDs such as "L<lexeme>-F<form>".
sense	Lexeme sense IDs such as "L<lexeme>-S<sense>".
any	API selector (e.g., flush(any)); not directly batchable.
unknown	Unrecognized/invalid identifier.

Definition at line 47 of file utils.hpp.

                       {
    item, 
    property, 
    lexeme, 
    mediainfo, 
    entity_schema, 
    form, 
    sense, 
    any, 
    unknown 
};

http_method

enum class corespace::http_method

strong

HTTP method to use for a request.

Represents the actual HTTP method used when sending a request.

• get: Use the HTTP GET method.
• post: Use the HTTP POST method.

Enumerator
get
post

Definition at line 201 of file utils.hpp.

{ get, post };

http_method_hint

enum class corespace::http_method_hint

strong

Hint for selecting the HTTP method for a request.

Used to determine which HTTP method to use based on query length or explicit override.

• automatic: Selects GET or POST based on query length (e.g., GET for short queries, POST for long).
• force_get: Forces the use of GET regardless of query length.
• force_post: Forces the use of POST regardless of query length.

This differs from http_method in that it provides a policy for method selection, rather than specifying the method directly.

Enumerator
automatic
force_get
force_post

Definition at line 215 of file utils.hpp.

{ automatic, force_get, force_post };

interface

enum class corespace::interface

strong

Enumerator
command_line
interactive

Definition at line 37 of file utils.hpp.

{ command_line, interactive };

service_kind

enum corespace::service_kind

Identifies supported SPARQL services.

Used to select which SPARQL endpoint to query. Currently only wdqs (Wikidata Query Service) is supported.

Values:

• wdqs: Wikidata Query Service (https://query.wikidata.org)

Enumerator
wdqs

Definition at line 74 of file utils.hpp.

{ wdqs };

Function Documentation

append_common_params()

void corespace::append_common_params	(	const service_kind	kind,
		const http_method	method,
		parameter_list &	params )

Appends common parameters required for a service and HTTP method.

Parameters

kind	The service kind.
method	The HTTP method.
params	The parameter list to append to. Modified in-place.

Note

Side effect: The input parameter list is extended.

Definition at line 105 of file utils.cpp.

  {
    switch (kind) {
    case service_kind::wdqs:
        if (method == http_method::get) {
            const bool has_format
                = std::ranges::any_of(params, [](const auto& param) {
                      return param.first == "format";
                  });
            if (!has_format) {
                params.emplace_back("format", "json");
            }
        }
        break;
    }
    sort_parameters(params);
}

References get, and wdqs.

choose_http_method()

http_method corespace::choose_http_method	(	const sparql_request &	request,
		const std::size_t	threshold )

Chooses the appropriate HTTP method for a SPARQL request.

Parameters

request	The SPARQL request.
threshold	The length threshold above which POST is preferred.

Returns

The selected HTTP method (GET or POST).

Definition at line 42 of file utils.cpp.

                                                                             {
    switch (request.method) {
    case http_method_hint::automatic:
        return request.query.size() <= threshold ? http_method::get
                                                 : http_method::post;
    case http_method_hint::force_get:
        return http_method::get;
    case http_method_hint::force_post:
        return http_method::post;
    }
    return http_method::get;
}

References automatic, force_get, force_post, get, corespace::sparql_request::method, post, and corespace::sparql_request::query.

Referenced by arachnespace::pheidippides::build_call_preview().

Here is the caller graph for this function:

get_service_profile()

const service_profile & corespace::get_service_profile

(

const service_kind

kind

)

Retrieve the service profile for a given service kind.

Parameters

kind	The service kind to look up.

Returns

Reference to the corresponding service_profile.

Definition at line 87 of file utils.cpp.

                                                                    {
    switch (kind) {
    case service_kind::wdqs:
        return wdqs_profile();
    default:
        throw std::invalid_argument("unknown service_kind");
    }
}

References wdqs, and wdqs_profile().

Referenced by arachnespace::pheidippides::build_call_preview().

Here is the call graph for this function:

Here is the caller graph for this function:

random_hex()

std::string corespace::random_hex

(

const std::size_t

n

)

Return exactly n random hexadecimal characters (lowercase).

The function draws 4-bit nibbles from the shared PRNG. Characters are not zero-padded beyond the requested length; each position is an independent, uniformly distributed hex digit.

Definition at line 33 of file rng.cpp.

                                        {
    static constexpr char digits[] = "0123456789abcdef";
    static thread_local std::uniform_int_distribution<int> nibble(0, 15);
 
    std::string out;
    out.resize(n);
    auto& g = rng();
    for (std::size_t i = 0; i < n; ++i) {
        out[i] = digits[nibble(g)];
    }
    return out;
}

References rng().

Referenced by arachnespace::arachne::new_group().

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_accept()

std::string corespace::resolve_accept	(	const sparql_request &	request,
		const service_profile &	profile,
		const std::string_view	override_accept )

Resolves the Accept header value for a SPARQL request.

Parameters

request	The SPARQL request.
profile	The service profile.
override_accept	Optional override for the Accept header.

Returns

The resolved Accept header value.

Definition at line 55 of file utils.cpp.

  {
    if (!request.accept.empty()) {
        return request.accept;
    }
    if (!override_accept.empty()) {
        return std::string { override_accept };
    }
    return profile.default_accept;
}

References corespace::sparql_request::accept, and corespace::service_profile::default_accept.

resolve_body_strategy()

std::pair< std::string, bool > corespace::resolve_body_strategy

(

const sparql_request &

request

)

Determines the body content and strategy for a SPARQL request.

Parameters

request

The SPARQL request.

Returns

A pair where:

• first: The body content as a string.
• second: A boolean indicating whether to use form body (true) or raw body (false).

Definition at line 69 of file utils.cpp.

                                                     {
    if (!request.content_type.empty()) {
        const bool use_form
            = request.content_type == "application/x-www-form-urlencoded";
        return { request.content_type, use_form };
    }
    if (request.method == http_method_hint::force_post) {
        return { "application/x-www-form-urlencoded", true };
    }
    return { "application/sparql-query", false };
}

References corespace::sparql_request::content_type, force_post, and corespace::sparql_request::method.

rng()

std::mt19937_64 & corespace::rng

(

)

Shared PRNG seeded on first use.

The generator is a process-wide std::mt19937_64 seeded from std::random_device. Calls from multiple threads share the same engine and therefore require external synchronization if deterministic ordering is important.

Definition at line 28 of file rng.cpp.

                     {
    static std::mt19937_64 gen { std::random_device {}() };
    return gen;
}

Referenced by random_hex().

Here is the caller graph for this function:

sort_parameters()

void corespace::sort_parameters

(

parameter_list &

params

)

Sorts the parameter list in-place by key.

Parameters

params

The parameter list to sort. Modified in-place.

Note

Side effect: The input parameter list is reordered.

Definition at line 96 of file utils.cpp.

                                             {
    std::ranges::sort(params, [](const auto& lhs, const auto& rhs) {
        if (lhs.first == rhs.first) {
            return lhs.second < rhs.second;
        }
        return lhs.first < rhs.first;
    });
}

wdqs_profile()

const service_profile & corespace::wdqs_profile

(

)

Definition at line 32 of file utils.cpp.

                                      {
    static const service_profile profile {
        .base_url = "https://query.wikidata.org/sparql",
        .default_accept = "application/sparql-results+json",
        .rate_hints = { "polite", "limit" }
    };
    return profile;
}

Referenced by get_service_profile().

Here is the caller graph for this function: