Skip to main content

financial_api/
market_dump.rs

1use std::fmt;
2
3use serde::{Deserialize, Deserializer};
4use time::OffsetDateTime;
5
6use crate::endpoints;
7use crate::{Client, Error, Response, ValidationError};
8
9/// 调试表示始终脱敏的短期预签名 URL。
10#[derive(Clone, PartialEq, Eq)]
11pub struct SecretUrl(String);
12
13impl SecretUrl {
14    /// 校验绝对 HTTP(S) 下载 URL。
15    pub fn new(value: impl Into<String>) -> Result<Self, ValidationError> {
16        let value = value.into();
17        let url = reqwest::Url::parse(&value)
18            .map_err(|_| ValidationError::new("presigned_url", "must be a valid absolute URL"))?;
19        if !matches!(url.scheme(), "http" | "https")
20            || url.host().is_none()
21            || !url.username().is_empty()
22            || url.password().is_some()
23        {
24            return Err(ValidationError::new(
25                "presigned_url",
26                "must be an absolute HTTP(S) URL without userinfo",
27            ));
28        }
29        Ok(Self(value))
30    }
31
32    /// 借用 URL 以立即下载。
33    #[must_use]
34    pub fn expose(&self) -> &str {
35        &self.0
36    }
37}
38
39impl<'de> Deserialize<'de> for SecretUrl {
40    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
41        let value = String::deserialize(deserializer)?;
42        Self::new(value).map_err(serde::de::Error::custom)
43    }
44}
45
46impl fmt::Debug for SecretUrl {
47    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
48        formatter.write_str("SecretUrl([REDACTED])")
49    }
50}
51
52/// 短期有效的市场数据包下载授权。
53#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
54pub struct MarketDumpUrl {
55    pub presigned_url: SecretUrl,
56    #[serde(with = "time::serde::rfc3339")]
57    pub presigned_url_expires_at: OffsetDateTime,
58}
59
60impl Client {
61    /// 获取完整十年日 K 线数据包的预签名下载地址。
62    ///
63    /// # 示例
64    #[doc = concat!(
65        "```no_run\n",
66        include_str!("../examples/market_dump_daily_k.rs"),
67        "\n```"
68    )]
69    pub async fn market_dump_daily_k(&self) -> Result<Response<MarketDumpUrl>, Error> {
70        self.market_dump_url(endpoints::DUMP_DAILY_K).await
71    }
72
73    /// 获取最近十个交易日日 K 线数据包的预签名下载地址。
74    ///
75    /// # 示例
76    #[doc = concat!(
77        "```no_run\n",
78        include_str!("../examples/market_dump_daily_k_10d.rs"),
79        "\n```"
80    )]
81    pub async fn market_dump_daily_k_10d(&self) -> Result<Response<MarketDumpUrl>, Error> {
82        self.market_dump_url(endpoints::DUMP_DAILY_K_10D).await
83    }
84
85    /// 获取完整复权事件数据包的预签名下载地址。
86    ///
87    /// # 示例
88    #[doc = concat!(
89        "```no_run\n",
90        include_str!("../examples/market_dump_adjustment_factors.rs"),
91        "\n```"
92    )]
93    pub async fn market_dump_adjustment_factors(&self) -> Result<Response<MarketDumpUrl>, Error> {
94        self.market_dump_url(endpoints::DUMP_ADJUSTMENT_FACTORS)
95            .await
96    }
97
98    async fn market_dump_url(&self, path: &str) -> Result<Response<MarketDumpUrl>, Error> {
99        self.get(path, &[] as &[(&str, &str)]).await
100    }
101}