feat(data): native Binance REST kline fetcher in 9 languages (#315)

Adds `BinanceRest::fetch_klines` to `wickra-data`: a blocking historical kline
downloader (`GET /api/v3/klines`) and the historical counterpart to the F4 live
`BinanceFeed`. It is the last native data-layer primitive needed to drop
third-party HTTP/JSON download helpers (`jackson`, `jsonlite`, `urllib`, …) from
the examples.

## What

- **Core** (`wickra-data`): `fetch_klines(symbol, interval, limit, start?, end?)`
  built on `ureq` with native-tls — sharing the exact same TLS backend
  (native-tls 0.2 / SChannel) as the existing tokio-tungstenite live feed, so the
  two pull one TLS stack, not two. Parses Binance's 12-element array rows via the
  existing serde infrastructure into validated `Candle`s. Blocking by design (a
  one-shot request needs no async runtime; the FFI boundary is synchronous
  anyway). Nine mock-HTTP-server tests cover parse / empty / limit / transport /
  JSON / invariant-violation paths.
- **C ABI**: `wickra_binance_fetch_klines(...)` (blocking drain into a caller
  buffer, `-1` on error) + regenerated cbindgen header and its vendored Go copy.
- **Bindings**: native Node `fetchBinanceKlines` / Python `fetch_binance_klines`;
  generated Go `FetchBinanceKlines` / C# `BinanceFeed.FetchKlines` / Java
  `BinanceFeed.fetchKlines` / R `fetch_binance_klines`. C / C++ call the C ABI
  directly. **WASM is excluded** (browsers use the host `fetch`).

The four C-ABI bindings are regenerated from the ScriptHelpers generators (not
hand-edited); the regen diff is exactly the new wrapper in each.

## Verification

All ten toolchains green locally: Rust (`cargo test`/`clippy`/`fmt`), Node, Python,
Go, C#, Java, R (`R CMD INSTALL` + smoke), WASM (`cargo check`, confirmed `ureq`
is not pulled). Each binding has an error-path smoke test; the parse/HTTP success
path is covered by the Rust mock-server tests.

No release in this PR — ships with the data-layer + numpy bundle later.
This commit is contained in:
kingchenc
2026-06-17 01:48:24 +02:00
committed by GitHub
parent b92ad32037
commit 2ae76bb90e
29 changed files with 863 additions and 209 deletions
+44
View File
@@ -28290,6 +28290,7 @@ fn _wickra(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
m.add_class::<PyResampler>()?;
m.add_class::<PyCandleReader>()?;
m.add_class::<PyBinanceFeed>()?;
m.add_function(wrap_pyfunction!(fetch_binance_klines, m)?)?;
// Candlestick patterns.
m.add_class::<PyDoji>()?;
m.add_class::<PyHammer>()?;
@@ -28679,6 +28680,49 @@ impl PyBinanceFeed {
}
}
/// Fetch historical klines from Binance's REST endpoint. `symbol` is the trading
/// pair (case-insensitive, e.g. `"BTCUSDT"`), `interval` the code `0..=15` (the
/// `Interval` declaration order), and `limit` the number of candles to request
/// (`1..=1000`). `start_ms`/`end_ms` are optional inclusive Unix-millisecond
/// bounds; `base_url` overrides the host (omit for production). Returns a list of
/// `(open, high, low, close, volume, timestamp)` tuples. This blocks until the
/// HTTP response arrives, releasing the GIL while it waits.
#[pyfunction]
#[pyo3(signature = (symbol, interval, limit, start_ms = None, end_ms = None, base_url = None))]
fn fetch_binance_klines(
py: Python<'_>,
symbol: &str,
interval: u8,
limit: u32,
start_ms: Option<i64>,
end_ms: Option<i64>,
base_url: Option<&str>,
) -> PyResult<Vec<CandleTuple>> {
let iv = binance_interval(interval)
.ok_or_else(|| PyValueError::new_err("unknown interval code (expected 0..=15)"))?;
let limit =
u16::try_from(limit).map_err(|_| PyValueError::new_err("limit must be in 1..=1000"))?;
let symbol = symbol.to_owned();
let base_url = base_url.map(str::to_owned);
let candles = py
.detach(move || match base_url {
Some(url) => {
let config = wickra_data::live::binance_rest::BinanceRestConfig { base_url: url };
wickra_data::live::binance_rest::fetch_klines_with_config(
&symbol, iv, limit, start_ms, end_ms, &config,
)
}
None => {
wickra_data::live::binance_rest::fetch_klines(&symbol, iv, limit, start_ms, end_ms)
}
})
.map_err(map_data_err)?;
Ok(candles
.into_iter()
.map(|c| (c.open, c.high, c.low, c.close, c.volume, c.timestamp))
.collect())
}
/// Roll trade ticks up into fixed-timeframe OHLCV candles.
#[pyclass(
name = "TickAggregator",