Pure search/discovery policy: percent-encoding, URL templating, and the zero-vs-broken result classifier. More...

#include "mdl_search.h"
#include <string.h>
#include "ra8_attributes.h"

Include dependency graph for mdl_search.c:

Enumerations
enum	mdl_search_const_t : uint8_t { k_hi_nibble_shift = 4U , k_nibble_mask = 0x0FU , k_triplet_len = 3U }
	Query-encoding constants. More...

Functions
const char *	mdl_search_placeholder (void)
	The {q} placeholder a search-URL template must contain.
static bool	internal_is_unreserved (unsigned char c)
	True for an RFC 3986 unreserved byte (copied verbatim).
static char	internal_hex_digit (unsigned nibble)
	Upper-case hex digit for a 0..15 nibble.
bool	mdl_query_encode (const char term, char out, size_t cap)
	Percent-encode a raw query term for safe inclusion in a URL.
bool	mdl_search_build_url (const char tmpl, const char encoded_term, char *out, size_t cap)
	Expand a query-URL template by substituting the encoded term for {q}.
mdl_search_outcome_t	mdl_search_classify (const mdl_hit_list_t *hits)
	Classify a parsed results page into an honest search outcome.
size_t	mdl_search_filter_series_hits (mdl_hit_list_t hits, const char chapter_marker)
	Remove chapter links and duplicate series URLs from discovery hits.

Variables
static const char	s_placeholder [] = "{q}"
	The {q} placeholder token, kept in one place.

Detailed Description

Pure search/discovery policy: percent-encoding, URL templating, and the zero-vs-broken result classifier.

Provides bounded query encoding and template expansion plus the result-list policy that distinguishes an honest empty result from changed markup. Filtering compacts caller-owned fixed storage in place and preserves discovery order.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file mdl_search.c.

Enumeration Type Documentation

◆ mdl_search_const_t

enum mdl_search_const_t : uint8_t

Query-encoding constants.

Enumerator
k_hi_nibble_shift	Bits to shift for the high hex nibble.
k_nibble_mask	Low-nibble mask.
k_triplet_len	Bytes a HH escape occupies.

Definition at line 20 of file mdl_search.c.

Function Documentation

◆ internal_hex_digit()

char internal_hex_digit ( unsigned nibble )

static

Upper-case hex digit for a 0..15 nibble.

Masks to the low nibble before indexing the constant digit table.

Parameters

[in] nibble Value whose low four bits are encoded.

Returns: Upper-case hexadecimal digit.

Return values

other One byte from 0-9 or A-F.

Precondition: Only the low nibble is significant.; Upper-case percent escapes are required.

Postcondition: No state is modified.; The result is an ASCII hex digit.

Note: Thread-safe: reads constant storage.

Since: 0.1.0

Definition at line 69 of file mdl_search.c.

References k_nibble_mask, and RA8_INTERNAL.

Referenced by mdl_query_encode().

◆ internal_is_unreserved()

bool internal_is_unreserved ( unsigned char c )

static

True for an RFC 3986 unreserved byte (copied verbatim).

Recognises ASCII alphanumeric bytes and the four unreserved marks.

Parameters

[in] c Byte to classify.

Returns: Whether percent-encoding may be omitted.

Return values

true	The byte is RFC 3986 unreserved.
false	The byte requires percent-encoding.

Precondition: c is one complete input byte.; Classification is intentionally ASCII-only.

Postcondition: No state is modified.; Input is unchanged.

Note: Thread-safe: pure comparison.

Since: 0.1.0

Definition at line 48 of file mdl_search.c.

References RA8_INTERNAL.

Referenced by mdl_query_encode().

◆ mdl_query_encode()

bool mdl_query_encode	(	const char *	term,
		char *	out,
		size_t	cap )

Percent-encode a raw query term for safe inclusion in a URL.

RFC 3986 encoding: the unreserved set (A-Z a-z 0-9 - . _ ~) is copied verbatim and every other byte – space, &, #, +, /, ?, and each byte of a multi-byte UTF-8 sequence – is written as HH with upper-case hex. Space becomes %20 (valid in both path and query), never +, so the result is unambiguous wherever the template places it.

Parameters

[in]	term	Raw term (may contain UTF-8 bytes), NUL-terminated.
[out]	out	Destination buffer for the NUL-terminated encoding.
[in]	cap	Capacity of `out` in bytes.

Returns: Whether the encoded term (plus its NUL) fit in out.

Return values

true	`out` holds the fully encoded term.
false	A NULL argument, cap == 0, or the encoding did not fit.

Precondition: term and out are non-NULL; out has room for cap bytes.; The caller treats false as "term too long", not "empty result".

Postcondition: On false with cap > 0, out[0] is '\0'.; On true, out contains only unreserved bytes and HH triplets.

Note: Thread-safe: writes only caller-provided storage.

See also: mdl_search_build_url

Since: 0.1.0

Definition at line 75 of file mdl_search.c.

References internal_hex_digit(), internal_is_unreserved(), k_hi_nibble_shift, and k_triplet_len.

Referenced by internal_discover_url().

◆ mdl_search_build_url()

bool mdl_search_build_url	(	const char *	tmpl,
		const char *	encoded_term,
		char *	out,
		size_t	cap )

Expand a query-URL template by substituting the encoded term for {q}.

Copies tmpl into out, replacing every {q} placeholder with encoded_term (already percent-encoded by mdl_query_encode). A template with no {q} is rejected – it could never carry the term, so silently fetching a fixed URL would be a lie about having searched.

Parameters

[in]	tmpl	Query-URL template holding at least one {q}.
[in]	encoded_term	The percent-encoded term to substitute.
[out]	out	Destination buffer for the NUL-terminated URL.
[in]	cap	Capacity of `out` in bytes.

Returns: Whether a URL containing the term was produced and fit.

Return values

true	`out` holds the expanded URL.
false	A NULL argument, cap == 0, no {q} in `tmpl`, or overflow.

Precondition: tmpl, encoded_term and out are non-NULL.; encoded_term came from mdl_query_encode (URL-safe bytes only).

Postcondition: On false with cap > 0, out[0] is '\0'.; On true, out contains encoded_term at each former {q}.

Note: Thread-safe: writes only caller-provided storage.

See also: mdl_query_encode

Since: 0.1.0

Definition at line 108 of file mdl_search.c.

References memcpy(), s_placeholder, strlen(), and strncmp().

Referenced by internal_discover_url().

◆ mdl_search_classify()

mdl_search_outcome_t mdl_search_classify ( const mdl_hit_list_t * hits )

Classify a parsed results page into an honest search outcome.

The whole point of #304's honesty criterion in one pure decision. With at least one matched hit the outcome is k_mdl_search_have_results. With none, the raw anchor tally decides: a page that rendered links but matched none is a genuine k_mdl_search_zero_results, while a page carrying no resolvable links at all is k_mdl_search_markup_changed – the endpoint returned something we could not read as a results page (its markup drifted, or the request was blocked or answered with non-HTML). A NULL list is treated as unreadable.

Parameters

[in] hits Parsed hit list from mdl_extract_hits, or NULL.

Returns: The outcome class for hits.

Return values

k_mdl_search_have_results	hits->count > 0.
k_mdl_search_zero_results	count == 0 and anchors_seen > 0.
k_mdl_search_markup_changed	NULL, or count == 0 and no anchors seen.

Precondition: hits, when non-NULL, was filled by mdl_extract_hits.; The caller prints a distinct message per returned class.

Postcondition: No state is modified.; The returned class depends only on count and anchors_seen.

Note: Thread-safe: reads only its argument.

See also: mdl_extract_hits

Since: 0.1.0

Definition at line 149 of file mdl_search.c.

References mdl_hit_list_t::anchors_seen, mdl_hit_list_t::count, k_mdl_search_have_results, k_mdl_search_markup_changed, and k_mdl_search_zero_results.

Referenced by mdl_discover_run().

◆ mdl_search_filter_series_hits()

size_t mdl_search_filter_series_hits	(	mdl_hit_list_t *	hits,
		const char *	chapter_marker )

Remove chapter links and duplicate series URLs from discovery hits.

Site result pages commonly mix canonical series links with recent chapter links. A descriptor's chapter marker therefore acts as an exclusion as well as the series-page extraction selector. Exact duplicate URLs are collapsed while preserving first-seen order.

Parameters

[in,out]	hits	Parsed hit list to compact in place.
[in]	chapter_marker	Chapter URL substring to reject; an empty string disables only the chapter filter.

Returns: Number of entries removed.

Return values

0	No entry was removed, or an argument was NULL.

Precondition: hits and chapter_marker are non-NULL.; Every populated hit URL is NUL-terminated within its fixed buffer.

Postcondition: hits contains only canonical, unique series candidates.; The retained candidates preserve their original relative order.

Note: Thread-safe when callers use distinct hit lists.

Since: 0.1.0

Definition at line 163 of file mdl_search.c.

References mdl_hit_list_t::count, mdl_hit_list_t::hits, strcmp(), strstr(), and mdl_hit_t::url.

Referenced by mdl_discover_run().

◆ mdl_search_placeholder()

const char * mdl_search_placeholder ( void )

The {q} placeholder a search-URL template must contain.

Returns: Borrowed pointer to the static placeholder token ("{q}").

Return values

non-NULL Always: the constant placeholder string.

Precondition: None.

Postcondition: No state is modified.

Note: Thread-safe: returns a constant.

Since: 0.1.0

Definition at line 29 of file mdl_search.c.

References s_placeholder.

Referenced by internal_discover_url().

Variable Documentation

◆ s_placeholder

const char s_placeholder[] = "{q}"

static

The {q} placeholder token, kept in one place.

Definition at line 27 of file mdl_search.c.

Referenced by mdl_search_build_url(), and mdl_search_placeholder().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ mdl_search_const_t

Function Documentation

◆ internal_hex_digit()

◆ internal_is_unreserved()

◆ mdl_query_encode()

◆ mdl_search_build_url()

◆ mdl_search_classify()

◆ mdl_search_filter_series_hits()

◆ mdl_search_placeholder()

Variable Documentation

◆ s_placeholder