twitch_oauth_token 4.0.1

Type-safe Twitch OAuth 2.0 authentication library with CSRF protection and full scope support
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

//! Global HTTP Client Management for Oauth Request
//!
//! See also [`Preset documentation`](https://docs.rs/asknothingx2-util/latest/asknothingx2_util/api/preset/struct.Preset.html)
//!
//! This module manages a single, shared HTTP client used by all TwitchOauth instances
//! in your application. This design provides several benefits:
//!
//! - **Connection pooling**: Reuses HTTP connections across OAuth operations
//! - **Consistent configuration**: Same timeouts, headers, etc. for all requests
//! - **Memory efficiency**: One client instead of many
//! - **Thread safety**: Can be safely used from multiple threads
//!
//! # Default Behavior (No Setup Required)
//!
//! If you don't call `setup()`, a default client is created automatically with:
//! - User-Agent: "twitch-oauth/1.0"
//! - Request timeout: 60s, Connect timeout: 10s
//! - Connections: 30 max per host, 90s idle timeout
//! - TLS: 1.2+ minimum, strict validation
//! - HTTPS: Enforced (HTTP blocked)
//! - HTTP/2: Required (no HTTP/1.1 fallback)
//! - Redirects: Up to 5 allowed
//! - Cookies: Not saved, Referer: Not sent (strict security)
//! - Headers: Accept JSON, no-cache control
//!
//! This works fine for most applications.
//!
//! # Basic Usage (No Setup)
//! ```no_run
//! # use twitch_oauth_token::TwitchOauth;
//! # async fn run() -> Result<(), twitch_oauth_token::Error> {
//! let oauth = TwitchOauth::new("client_id", "client_secret");
//! let token = oauth.app_access_token().await?;
//! # Ok(())
//! # }
//! ```
//!
//! # Custom Configuration
//! ```no_run
//! use std::time::Duration;
//!
//! use asknothingx2_util::api::preset;
//! use twitch_oauth_token::{client, TwitchOauth};
//!
//! # async fn run() -> Result<(), twitch_oauth_token::Error> {
//! let mut preset = preset::authentication("MyApp/1.0");
//! preset
//!     .timeouts(Duration::from_secs(60), Duration::from_secs(30))
//!     .connections(10, Duration::from_secs(90));
//!
//! preset
//!     .default_headers_mut()
//!     .accept_json()
//!     .content_type_json();
//!
//! // Configure once at startup
//! client::setup(preset.build()?)?;
//!
//! // Now all OAuth instances use your custom client
//! let oauth = TwitchOauth::new("client_id", "client_secret");
//! # Ok(())
//! # }
//!
//! ```
use std::sync::OnceLock;

use asknothingx2_util::api::preset;
use reqwest::Client;

use crate::{error, Error};

static CLIENT: OnceLock<Client> = OnceLock::new();

/// Configure the global HTTP client used for all OAuth requests
///
/// This should be called once at application startup if you need custom
/// timeouts, proxies, or other HTTP client configuration.
///
/// # Example
/// ```no_run
/// use std::time::Duration;
///
/// use asknothingx2_util::api::preset;
/// use twitch_oauth_token::client;
///
/// # fn run() -> Result<(), twitch_oauth_token::Error> {
/// let mut preset = preset::authentication("MyApp/1.0");
/// preset
///     .timeouts(Duration::from_secs(60), Duration::from_secs(30))
///     .connections(10, Duration::from_secs(90));
///
/// preset
///     .default_headers_mut()
///     .accept_json()
///     .content_type_json();
///
/// client::setup(preset.build()?)?;
/// # Ok(())
/// # }
/// ```
pub fn setup(client: reqwest::Client) -> Result<(), Error> {
    if CLIENT.get().is_some() {
        return Err(error::client_setup::already_initialized());
    }

    CLIENT
        .set(client)
        .map_err(|_| error::client_setup::already_initialized())?;

    Ok(())
}

/// Get the global HTTP client (creates default if not configured)
pub fn get() -> &'static Client {
    CLIENT.get_or_init(|| {
        preset::authentication(concat!(
            env!("CARGO_PKG_NAME"),
            "/",
            env!("CARGO_PKG_VERSION")
        ))
        .build()
        .expect("failed to build default http client")
    })
}