traq_bot_http/lib.rs
1#![cfg_attr(docsrs, feature(doc_auto_cfg, doc_cfg))]
2
3//! [](https://github.com/H1rono/traq-bot-http-rs/blob/main/LICENSE)
4//! [](https://crates.io/crates/traq-bot-http)
5//! [](https://github.com/H1rono/traq-bot-http-rs/releases/latest)
6//! [](https://crates.io/crates/traq-bot-http)
7//!
8//! traQ BOTのPOSTリクエストをパースするライブラリです。
9//!
10//! [examples](https://github.com/H1rono/traq-bot-http-rs/blob/main/examples)
11
12mod error;
13mod events;
14pub(crate) mod macros;
15pub mod parser;
16pub mod payloads;
17
18#[cfg(feature = "tower")]
19pub mod handler;
20
21use std::sync::Arc;
22
23pub use error::{Error, ErrorKind, Result};
24pub use events::{Event, EventKind};
25
26/// HTTP POSTリクエストのパーサー
27#[must_use]
28#[derive(Debug, Clone)]
29pub struct RequestParser {
30 inner: Arc<parser::Inner>,
31}
32
33#[cfg(feature = "tower")]
34/// イベントハンドラです。
35///
36/// # Example
37///
38/// ```
39/// use std::convert::Infallible;
40///
41/// use tower::service_fn;
42/// use traq_bot_http::{payloads, RequestParser};
43///
44/// async fn on_ping((state, payload): (i32, payloads::PingPayload)) -> Result<(), Infallible> {
45/// println!("state: {state:?}, ping: {payload:?}");
46/// // assert_eq!(state, 0);
47/// Ok(())
48/// }
49///
50/// let parser = RequestParser::new("verification_token");
51/// let handler = parser
52/// .into_handler()
53/// .on_ping(service_fn(on_ping))
54/// .with_state(0i32);
55/// # let _ = handler;
56/// ```
57///
58/// # Composing Handler
59///
60/// [`Handler`] はメソッドチェーンにより構成されます。使用可能なメソッドは以下の通りです。
61///
62/// - [`.on_*<S>(S)`]
63/// - `*`には [`EventKind`] の variant が `snake_case` で入ります。
64/// - 例: [`Handler::on_message_created`]
65/// - [`.with_state<S>(S)`]
66///
67/// 適切に構成された [`Handler`] は [`Service`] trait を実装します。各メソッドのドキュメントを参照してください。
68///
69/// **[`Handler`] の構成時にはコンパイルエラーが出ない可能性があります** 。
70/// [`Service`] trait を使用するライブラリ (axum 等) の条件も確認してください。
71///
72/// # Note
73///
74/// この構造体の型パラメータは **unstable** です。`Handler<T>`における`T`は予告なく変化する可能性があります。
75///
76/// [`handler`]: crate::handler
77/// [`Service`]: tower::Service
78/// [`.on_*<S>(S)`]: crate::Handler::on_ping
79/// [`.with_state<S>(S)`]: crate::Handler::with_state
80#[must_use]
81#[derive(Debug, Clone)]
82pub struct Handler<Service> {
83 service: Service,
84 parser: RequestParser,
85}
86
87#[cfg(test)]
88pub(crate) mod test_utils;