feat(quote): add QuoteTransport to serve quote pull APIs over HTTP

[hogan-yuan]

What

Adds Config::quote_transport(QuoteTransport::{WebSocket, Http}) (env LONGBRIDGE_QUOTE_TRANSPORT=ws|http, default WebSocket). With Http, the 20 QuoteContext pull methods backed by the 19 WebSocket commands that have a REST equivalent (static_info, quote, option_quote, warrant_quote, depth, brokers, participants, trades, intraday, candlesticks, history_candlesticks_by_offset/by_date, option_chain_expiry_date_list, warrant_issuers, warrant_list, trading_session, trading_days, capital_flow, capital_distribution, calc_indexes) go over POST /quote/* instead of the quote WebSocket. A process that only pulls data never opens a WebSocket connection. Public method signatures and return types are unchanged.

The option is exposed in all six layers (Rust, C, C++, Java, Node.js, Python), mirroring PushCandlestickMode.

Why

longbridge/longbridge-mcp#162 re-implemented every quote tool on top of the REST endpoints inside the MCP (per-tool JSON reshaping) to get rid of its per-user WebSocket pool. That logic belongs in the SDK: one switch in QuoteContext::request, and every SDK consumer (MCP, CLI, …) gets it with identical types.

Usage

Opt in per Config (default stays WebSocket, so nothing changes for existing users). Either set the env var:

export LONGBRIDGE_QUOTE_TRANSPORT=http   # ws (default) | http

or set it in code. After that, call the quote APIs exactly as before — same methods, same return types:

Rust

use std::sync::Arc;

use longbridge::{Config, QuoteTransport, quote::QuoteContext};

let config = Arc::new(Config::from_apikey_env()?.quote_transport(QuoteTransport::Http));
let (ctx, _) = QuoteContext::new(config);
let quotes = ctx.quote(["700.HK", "AAPL.US"]).await?; // POST /quote/quotes, no WebSocket opened

Python

from longbridge.openapi import Config, QuoteContext, QuoteTransport

config = Config.from_apikey(app_key, app_secret, access_token, quote_transport=QuoteTransport.Http)
ctx = QuoteContext(config)
quotes = ctx.quote(["700.HK", "AAPL.US"])

Node.js

const { Config, QuoteContext, QuoteTransport } = require("longbridge");

const config = Config.fromApikey(appKey, appSecret, accessToken, { quoteTransport: QuoteTransport.Http });
const ctx = QuoteContext.new(config);

Java

Config config = Config.fromApikeyEnv().quoteTransport(QuoteTransport.Http);

C++

Status status;
Config config = Config::from_apikey_env(status);
config.set_quote_transport(QuoteTransport::Http);

C

lb_config_t *config = lb_config_from_apikey_env(&error);
lb_config_set_quote_transport(config, QuoteTransport_Http);

Notes:

• Subscriptions / push callbacks, realtime_*, member_id / quote_level / quote_package_details still use the WebSocket, which is then connected on first use. A process that only calls the pull APIs never opens it.
• enable_overnight keeps its meaning on both transports (US overnight data is returned only when it is set).
• Comparison tool: cd examples/rust && cargo run -p quote_http_compare calls every pull API over both transports and prints the diff.

How

• rust/src/quote/cmd_code.rs::http_path maps WS command codes to REST paths; QuoteContext::request / request_without_body branch on the transport. The request is the same prost message serialised as JSON (nulls stripped); the response is decoded into the same prost message by rust/src/quote/http_json.rs, a lenient serde deserializer (int64-as-string, omitted/null → default, camelCase keys, unknown fields ignored), so all existing TryFrom conversions are reused.
• rust/src/quote/overnight.rs aligns the one known server-side difference: REST always returns US overnight data and has no opt-out, while the WS only returns it when enable_overnight is set. On the HTTP path (and only there) the SDK applies the same rule for US equities: clears overnight_quote, filters overnight intraday lines and, for TradeSessions::All candlestick queries, drops OvernightTrade bars and tops up count/range-capped windows with POST /quote/history-candlesticks offset queries (≤1000 per request, ≤8 rounds; when a page yields nothing the cursor is inside the contiguous overnight block and the next page is a full 1000 to jump it; a shortfall is logged). The WebSocket path is functionally identical to main (the only visible change is the brokers region-restriction error path, "quote/brokers (WebSocket)" → "quote/brokers"). HTTP-path requests are logged through the quote context's log subscriber like every other SDK HTTP call.
• examples/rust/quote_http_compare calls every pull API over both transports and diffs the results.

Verification

examples/rust/quote_http_compare was run against a staging environment and production, with overnight on and off:

• Staging: 31/33 cases identical in both modes; the 2 remaining are the gateway error-code gap below.
• Production: all successful cases structurally identical; the remaining value-level differences are a backend issue (two consecutive REST calls disagree with each other while the WS is stable — different /quote/* replicas serve different data).
• cargo test -p longbridge --lib quote:: 20/20 (refill paging incl. the overnight-block jump in both directions, window targets, US overnight window in EDT/EST, proto-JSON decode edge cases, request null-stripping and the JSON sent for top-up offset queries); cargo clippy --all --all-features adds no warnings; cargo +nightly fmt --all.
• Follow-up commits address review: overnight-block refill escalation, a single US-equity / TradeSessions::All predicate (suffix matched case-insensitively), window_target (a date-range page is capped only if it is full-size and does not reach start), HTTP logging through the SDK log subscriber, a warning only when the top-up hits its round limit, CHANGELOG caveats (incl. intraday possibly empty over HTTP during the overnight session) (top-up endpoint and request count, error variant, missing per-command rate limit, 429 retry, overnight-session values), "websocket" env alias removed. Please squash on merge.

Known gateway gaps (not fixable in the SDK)

1. REST reports business errors as 500 internal server error instead of passing the code through (WS: 301600, 301604, 301607). Callers that branch on error codes will not work over HTTP until this is fixed.
2. Production /quote/* data is not consistent across replicas.
3. No REST opt-out for US overnight data (handled client-side here as a stopgap; quote::overnight should be removed once the REST endpoints honour need_over_night_quote).

Follow-up (not in this PR): a client-side rate limit / jittered retry for the HTTP path, which today relies only on the HTTP client's 429 back-off.

🤖 Generated with Claude Code