the history-stale-threshold flag - what exactly happens when history is stale?

Question

A recent(ish?) addition to the horizon configuration is the

viper.BindEnv("history-stale-threshold", "HISTORY_STALE_THRESHOLD")

the doc says:

"the maximum number of ledgers the history db is allowed to be out of date from the connected stellar-core db before horizon considers history stale"

but what exactly does it mean to "consider history stake"? will horizon stop working? return 5xx?

Answer 1

This is described in the Horizon administration guide:

Horizon ingests ledger data from a connected instance of stellar-core. In the event that stellar-core stops running (or if Horizon stops ingesting data for any other reason), the view provided by Horizon will start to lag behind reality. For simpler applications, this may be fine, but in many cases this lag is unacceptable and the application should not continue operating until the lag is resolved.

To help applications that cannot tolerate lag, Horizon provides a configurable "staleness" threshold. Given that enough lag has accumulated to surpass this threshold (expressed in number of ledgers), Horizon will only respond with an error: stale_history. To configure this option, use either the --history-stale-threshold command line flag or the HISTORY_STALE_THRESHOLD environment variable. NOTE: non-historical requests (such as submitting transactions or finding payment paths) will not error out when the staleness threshold is surpassed.