- Generated by
1.16.1
|
ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
|
Governed search/browse: build the query URL, fetch it politely, parse the hits, and present them honestly (with optional select-for-download). More...
#include "mdl_discover.h"#include <stdio.h>#include <string.h>#include "mdl_fetch_internal.h"#include "mdl_net.h"#include "mdl_search.h"#include "mdl_stream_internal.h"#include "mdl_url_guard.h"#include "ra8_attributes.h"#include "ra8_err.h"Go to the source code of this file.
Enumerations | |
| enum | mdl_discover_size_t : uint16_t { k_disc_url_max = 1024 , k_disc_term_max = 768 , k_disc_max_attempts = 4 } |
| Local buffer sizes and the bounded governed-retry budget. More... | |
Functions | |
| static void | internal_discover_text3 (const mdl_discover_req_t *req, ra8_io_stream_t *stream, const char *first, const char *second, const char *third) |
| Append three discovery fragments and latch the first sink failure. | |
| static uint32_t | internal_max_u32 (uint32_t a, uint32_t b) |
| Larger of two unsigned values. | |
| static const char * | internal_mode_word (mdl_discover_mode_t m) |
| The human word for a discovery mode, for diagnostics. | |
| static bool | internal_discover_url (const mdl_discover_req_t *req, char *out, size_t cap, int *rc) |
| Build the results URL for this run; false + message on a config gap. | |
| static ra8_err_t | internal_discover_fetch (const mdl_discover_req_t *req, const char *url, size_t *out_len, long *out_status) |
| Robots-gate and governed-fetch the results page into req->page_buf. | |
| static void | internal_print_header (const mdl_discover_req_t *req, size_t n) |
| Print the numbered results header for the run's mode. | |
| static void | internal_print_hits (const mdl_discover_req_t *req) |
| Print every hit as [N] title over its series URL. | |
| static void | internal_print_zero (const mdl_discover_req_t *req) |
| The honest "no results" message, distinct from a broken page. | |
| static void | internal_print_markup_changed (const mdl_discover_req_t *req) |
| The honest "the markup changed" message, distinct from no results. | |
| static bool | internal_select_hit (const mdl_discover_req_t *req, const mdl_hit_t *chosen, size_t pick, char *out_url, size_t out_cap) |
| Copy the picked hit's URL out and announce it; false + message on overrun. | |
| static int | internal_present_and_pick (const mdl_discover_req_t *req, mdl_search_outcome_t outcome, size_t pick, char *out_url, size_t out_cap) |
| Present the outcome and, when pick != 0, resolve the selection. | |
| int | mdl_discover_run (const mdl_discover_req_t *req, size_t pick, char *out_url, size_t out_cap) |
| Run one search/browse discovery: fetch, parse, present, and select. | |
Governed search/browse: build the query URL, fetch it politely, parse the hits, and present them honestly (with optional select-for-download).
Uses injected network, policy, output, and diagnostic dependencies for bounded discovery and explicit selection.
Definition in file mdl_discover.c.
| enum mdl_discover_size_t : uint16_t |
Local buffer sizes and the bounded governed-retry budget.
| Enumerator | |
|---|---|
| k_disc_url_max | Composed results-URL buffer bytes. |
| k_disc_term_max | Percent-encoded term buffer bytes. |
| k_disc_max_attempts | 1 initial + up to 3 governed retries. |
Definition at line 24 of file mdl_discover.c.
|
static |
Robots-gate and governed-fetch the results page into req->page_buf.
One request through the shared governor, with bounded backoff retries on a retryable class – search is never a rate-limit bypass.
| [in] | req | Validated request description. |
| [in] | url | NUL-terminated URL input. |
| [out] | out_len | Receives the produced byte length. |
| [out] | out_status | Receives the protocol status. |
| k_ra8_ok | The operation completed successfully. |
| other | The originating validation, storage, stream, or network error. |
Definition at line 182 of file mdl_discover.c.
References mdl_site_t::chapter_delay_max, mdl_site_t::chapter_delay_min, mdl_discover_req_t::gov, internal_max_u32(), k_disc_max_attempts, k_mdl_gov_host_max, k_ra8_err_would_block, k_ra8_fail, mdl_governor_acquire(), mdl_governor_observe(), mdl_governor_release(), mdl_net_get_buf(), mdl_session_url_allowed(), mdl_url_host(), mdl_session_t::net, mdl_discover_req_t::page_buf, mdl_discover_req_t::page_cap, priv_mdl_fetch_is_retryable(), RA8_INTERNAL, mdl_net_resp_t::retry_after, mdl_discover_req_t::session, mdl_discover_req_t::site, mdl_net_resp_t::status, mdl_discover_req_t::timeout_ms, and mdl_session_t::user_agent.
Referenced by mdl_discover_run().
|
static |
Append three discovery fragments and latch the first sink failure.
Uses injected stream and network state while preserving the first error. An unvalidated or out-of-range selection is never reported as success.
| [in] | req | Validated request description. |
| [in,out] | stream | Destination stream state. |
| [in] | first | First text fragment. |
| [in] | second | Second text fragment. |
| [in] | third | Third text fragment. |
Definition at line 45 of file mdl_discover.c.
References mdl_discover_req_t::io_error, k_ra8_ok, priv_mdl_stream_text(), and RA8_INTERNAL.
Referenced by internal_discover_url(), internal_present_and_pick(), internal_print_markup_changed(), internal_select_hit(), and mdl_discover_run().
|
static |
Build the results URL for this run; false + message on a config gap.
Sets *rc to 2 (capability/usage) on every false return.
| [in] | req | Validated request description. |
| [out] | out | Caller-owned result storage. |
| [in] | cap | Destination capacity including any terminator. |
| [out] | rc | Status accumulator updated on failure. |
out. | true | The documented predicate holds or the requested operation completed. |
| false | The predicate does not hold or validation rejected the operation. |
Definition at line 107 of file mdl_discover.c.
References mdl_site_t::browse_url, mdl_discover_req_t::diagnostic, internal_discover_text3(), mdl_discover_req_t::io_error, k_disc_term_max, k_mdl_discover_browse, k_ra8_ok, mdl_query_encode(), mdl_search_build_url(), mdl_search_placeholder(), mdl_discover_req_t::mode, mdl_site_t::search_url, mdl_discover_req_t::site, and mdl_discover_req_t::term.
Referenced by mdl_discover_run().
|
static |
Larger of two unsigned values.
Uses injected stream and network state while preserving the first error. An unvalidated or out-of-range selection is never reported as success.
| [in] | a | First unsigned operand. |
| [in] | b | Second unsigned operand. |
a and b. | 0 | Both operands were zero. |
| other | The larger nonzero operand. |
Definition at line 77 of file mdl_discover.c.
References RA8_INTERNAL.
Referenced by internal_discover_fetch().
|
static |
The human word for a discovery mode, for diagnostics.
Definition at line 83 of file mdl_discover.c.
References k_mdl_discover_search, and RA8_INTERNAL.
Referenced by internal_present_and_pick(), and mdl_discover_run().
|
static |
Present the outcome and, when pick != 0, resolve the selection.
Uses injected stream and network state while preserving the first error. An unvalidated or out-of-range selection is never reported as success.
| [in] | req | Validated request description. |
| [in] | outcome | Parsed discovery outcome. |
| [in] | pick | One-based selected hit index. |
| [out] | out_url | Receives the selected absolute URL. |
| [in] | out_cap | Destination capacity including any terminator. |
| 0 | Results were presented and any requested selection was valid. |
| 1 | Markup classification or stream output failed. |
| 2 | The requested selection or output buffer was invalid. |
Definition at line 416 of file mdl_discover.c.
References mdl_hit_list_t::count, mdl_discover_req_t::diagnostic, mdl_discover_req_t::hits, mdl_hit_list_t::hits, internal_discover_text3(), internal_mode_word(), internal_print_header(), internal_print_hits(), internal_print_markup_changed(), internal_print_zero(), internal_select_hit(), mdl_discover_req_t::io_error, k_mdl_discover_search, k_mdl_search_have_results, k_mdl_search_markup_changed, k_mdl_search_zero_results, k_ra8_ok, mdl_discover_req_t::mode, mdl_discover_req_t::output, priv_mdl_stream_text(), priv_mdl_stream_u64(), and RA8_INTERNAL.
Referenced by mdl_discover_run().
|
static |
Print the numbered results header for the run's mode.
Uses injected stream and network state while preserving the first error. An unvalidated or out-of-range selection is never reported as success.
| [in] | req | Validated request description. |
| [in] | n | Element or byte count. |
Definition at line 229 of file mdl_discover.c.
References mdl_site_t::host, mdl_discover_req_t::io_error, k_mdl_discover_search, k_ra8_ok, mdl_discover_req_t::mode, mdl_discover_req_t::output, priv_mdl_stream_text(), priv_mdl_stream_u64(), RA8_INTERNAL, mdl_discover_req_t::site, and mdl_discover_req_t::term.
Referenced by internal_present_and_pick().
|
static |
Print every hit as [N] title over its series URL.
Uses injected stream and network state while preserving the first error. An unvalidated or out-of-range selection is never reported as success.
| [in] | req | Validated request description. |
Definition at line 260 of file mdl_discover.c.
References mdl_hit_list_t::count, mdl_discover_req_t::hits, mdl_hit_list_t::hits, mdl_discover_req_t::io_error, k_ra8_ok, mdl_discover_req_t::output, priv_mdl_stream_text(), priv_mdl_stream_u64(), RA8_INTERNAL, mdl_hit_t::title, and mdl_hit_t::url.
Referenced by internal_present_and_pick().
|
static |
The honest "the markup changed" message, distinct from no results.
Uses injected stream and network state while preserving the first error. An unvalidated or out-of-range selection is never reported as success.
| [in] | req | Validated request description. |
Definition at line 336 of file mdl_discover.c.
References mdl_discover_req_t::diagnostic, mdl_site_t::host, internal_discover_text3(), RA8_INTERNAL, and mdl_discover_req_t::site.
Referenced by internal_present_and_pick().
|
static |
The honest "no results" message, distinct from a broken page.
Uses injected stream and network state while preserving the first error. An unvalidated or out-of-range selection is never reported as success.
| [in] | req | Validated request description. |
Definition at line 289 of file mdl_discover.c.
References mdl_hit_list_t::anchors_seen, mdl_discover_req_t::diagnostic, mdl_discover_req_t::hits, mdl_site_t::host, mdl_discover_req_t::io_error, k_mdl_discover_search, k_ra8_ok, mdl_discover_req_t::mode, priv_mdl_stream_text(), priv_mdl_stream_u64(), RA8_INTERNAL, mdl_site_t::search_result_contains, mdl_discover_req_t::site, and mdl_discover_req_t::term.
Referenced by internal_present_and_pick().
|
static |
Copy the picked hit's URL out and announce it; false + message on overrun.
Uses injected stream and network state while preserving the first error. An unvalidated or out-of-range selection is never reported as success.
| [in] | req | Validated request description. |
| [in] | chosen | Selected discovery hit. |
| [in] | pick | One-based selected hit index. |
| [out] | out_url | Receives the selected absolute URL. |
| [in] | out_cap | Destination capacity including any terminator. |
| true | The documented predicate holds or the requested operation completed. |
| false | The predicate does not hold or validation rejected the operation. |
Definition at line 365 of file mdl_discover.c.
References mdl_discover_req_t::diagnostic, internal_discover_text3(), mdl_discover_req_t::io_error, k_ra8_ok, mdl_discover_req_t::output, priv_mdl_stream_text(), priv_mdl_stream_u64(), RA8_INTERNAL, mdl_hit_t::title, and mdl_hit_t::url.
Referenced by internal_present_and_pick().
| int mdl_discover_run | ( | const mdl_discover_req_t * | req, |
| size_t | pick, | ||
| char * | out_url, | ||
| size_t | out_cap ) |
Run one search/browse discovery: fetch, parse, present, and select.
Builds the results URL for req->mode from the site descriptor (encoding the term and expanding {q} for search; using browse_url verbatim for browse), refuses when the descriptor supplies no such endpoint, gates the URL against robots.txt, and fetches it through req->gov with bounded governed retries. It then parses the response with mdl_extract_hits and classifies it with mdl_search_classify, printing a distinct message for each honest outcome so an empty result is never dressed up as a successful search. When pick is non-zero it names the pick-th hit (1-based) and copies its series URL into out_url for a follow-on download.
| [in] | req | Injected dependencies and inputs (never NULL). |
| [in] | pick | 1-based hit to select, or 0 to only list results. |
| [out] | out_url | Receives the selected series URL, or "" when nothing was selected. May be NULL only when pick is 0. |
| [in] | out_cap | Capacity of out_url in bytes (>= 1 when out_url set). |
| 0 | Listed results (possibly zero) or selected a hit successfully. |
| 1 | The request failed, or the page could not be read as results, or a pick was requested with no results to choose from. |
| 2 | A capability/usage error: no such discovery endpoint configured, an empty/oversized term, or a pick index out of range. |
req and its session/gov/site/page_buf/hits are non-NULL. out_url has room for out_cap bytes when pick is non-zero. req->hits holds the parsed hits for the run. pick != 0.Definition at line 471 of file mdl_discover.c.
References mdl_site_t::chapter_url_contains, mdl_discover_req_t::diagnostic, mdl_discover_req_t::gov, mdl_discover_req_t::hits, internal_discover_fetch(), internal_discover_text3(), internal_discover_url(), internal_mode_word(), internal_present_and_pick(), mdl_discover_req_t::io_error, k_disc_url_max, k_mdl_reason_max, k_ra8_ok, mdl_extract_hits(), mdl_search_classify(), mdl_search_filter_series_hits(), mdl_discover_req_t::mode, mdl_discover_req_t::output, mdl_discover_req_t::page_buf, priv_mdl_fetch_reason(), priv_mdl_stream_text(), mdl_site_t::search_result_contains, mdl_discover_req_t::session, and mdl_discover_req_t::site.
Referenced by mdl_app_run_discover().
1.16.1