1
0
mirror of https://github.com/actix/actix-extras.git synced 2025-03-15 01:46:26 +01:00

242 lines
16 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Source of the Rust file `actix-session/src/storage/cookie.rs`."><meta name="keywords" content="rust, rustlang, rust-lang"><title>cookie.rs - source</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../../../SourceSerif4-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../../FiraSans-Regular.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../../FiraSans-Medium.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../../SourceCodePro-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../../SourceSerif4-Bold.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../../SourceCodePro-Semibold.ttf.woff2"><link rel="stylesheet" type="text/css" href="../../../normalize.css"><link rel="stylesheet" type="text/css" href="../../../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../../../ayu.css" disabled><link rel="stylesheet" type="text/css" href="../../../dark.css" disabled><link rel="stylesheet" type="text/css" href="../../../light.css" id="themeStyle"><script id="default-settings" ></script><script src="../../../storage.js"></script><script src="../../../crates.js"></script><script defer src="../../../main.js"></script><script defer src="../../../source-script.js"></script><script defer src="../../../source-files.js"></script>
<noscript><link rel="stylesheet" href="../../../noscript.css"></noscript><link rel="icon" href="https://actix.rs/favicon.ico"></head><body class="rustdoc source"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">&#9776;</button><a class="sidebar-logo" href="../../../actix_session/index.html"><div class="logo-container"><img src="https://actix.rs/img/logo.png" alt="logo"></div>
</a><h2 class="location"></h2>
</nav>
<nav class="sidebar"><a class="sidebar-logo" href="../../../actix_session/index.html"><div class="logo-container">
<img src="https://actix.rs/img/logo.png" alt="logo"></div>
</a></nav><main><div class="width-limiter"><div class="sub-container"><a class="sub-logo-container" href="../../../actix_session/index.html">
<img src="https://actix.rs/img/logo.png" alt="logo"></a><nav class="sub"><div class="theme-picker hidden"><button id="theme-picker" aria-label="Pick another theme!" aria-haspopup="menu" title="themes"><img width="22" height="22" alt="Pick another theme!" src="../../../brush.svg"></button><div id="theme-choices" role="menu"></div></div><form class="search-form"><div class="search-container"><span></span><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press S to search, ? for more options…" type="search"><button type="button" id="help-button" title="help">?</button><a id="settings-menu" href="../../../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../../../wheel.svg"></a></div></form></nav></div><section id="main-content" class="content"><div class="example-wrap"><pre class="line-numbers"><span id="1">1</span>
<span id="2">2</span>
<span id="3">3</span>
<span id="4">4</span>
<span id="5">5</span>
<span id="6">6</span>
<span id="7">7</span>
<span id="8">8</span>
<span id="9">9</span>
<span id="10">10</span>
<span id="11">11</span>
<span id="12">12</span>
<span id="13">13</span>
<span id="14">14</span>
<span id="15">15</span>
<span id="16">16</span>
<span id="17">17</span>
<span id="18">18</span>
<span id="19">19</span>
<span id="20">20</span>
<span id="21">21</span>
<span id="22">22</span>
<span id="23">23</span>
<span id="24">24</span>
<span id="25">25</span>
<span id="26">26</span>
<span id="27">27</span>
<span id="28">28</span>
<span id="29">29</span>
<span id="30">30</span>
<span id="31">31</span>
<span id="32">32</span>
<span id="33">33</span>
<span id="34">34</span>
<span id="35">35</span>
<span id="36">36</span>
<span id="37">37</span>
<span id="38">38</span>
<span id="39">39</span>
<span id="40">40</span>
<span id="41">41</span>
<span id="42">42</span>
<span id="43">43</span>
<span id="44">44</span>
<span id="45">45</span>
<span id="46">46</span>
<span id="47">47</span>
<span id="48">48</span>
<span id="49">49</span>
<span id="50">50</span>
<span id="51">51</span>
<span id="52">52</span>
<span id="53">53</span>
<span id="54">54</span>
<span id="55">55</span>
<span id="56">56</span>
<span id="57">57</span>
<span id="58">58</span>
<span id="59">59</span>
<span id="60">60</span>
<span id="61">61</span>
<span id="62">62</span>
<span id="63">63</span>
<span id="64">64</span>
<span id="65">65</span>
<span id="66">66</span>
<span id="67">67</span>
<span id="68">68</span>
<span id="69">69</span>
<span id="70">70</span>
<span id="71">71</span>
<span id="72">72</span>
<span id="73">73</span>
<span id="74">74</span>
<span id="75">75</span>
<span id="76">76</span>
<span id="77">77</span>
<span id="78">78</span>
<span id="79">79</span>
<span id="80">80</span>
<span id="81">81</span>
<span id="82">82</span>
<span id="83">83</span>
<span id="84">84</span>
<span id="85">85</span>
<span id="86">86</span>
<span id="87">87</span>
<span id="88">88</span>
<span id="89">89</span>
<span id="90">90</span>
<span id="91">91</span>
<span id="92">92</span>
<span id="93">93</span>
<span id="94">94</span>
<span id="95">95</span>
<span id="96">96</span>
<span id="97">97</span>
<span id="98">98</span>
<span id="99">99</span>
<span id="100">100</span>
<span id="101">101</span>
<span id="102">102</span>
<span id="103">103</span>
<span id="104">104</span>
<span id="105">105</span>
<span id="106">106</span>
<span id="107">107</span>
<span id="108">108</span>
<span id="109">109</span>
<span id="110">110</span>
<span id="111">111</span>
<span id="112">112</span>
<span id="113">113</span>
<span id="114">114</span>
<span id="115">115</span>
<span id="116">116</span>
</pre><pre class="rust"><code><span class="kw">use</span> <span class="ident">std::convert::TryInto</span>;
<span class="kw">use</span> <span class="ident">time::Duration</span>;
<span class="kw">use</span> <span class="ident"><span class="kw">super</span>::SessionKey</span>;
<span class="kw">use</span> <span class="ident"><span class="kw">crate</span>::storage</span>::{
<span class="ident">interface</span>::{<span class="ident">LoadError</span>, <span class="ident">SaveError</span>, <span class="ident">SessionState</span>, <span class="ident">UpdateError</span>},
<span class="ident">SessionStore</span>,
};
<span class="doccomment">/// Use the session key, stored in the session cookie, as storage backend for the session state.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// ```no_run</span>
<span class="doccomment">/// use actix_web::{cookie::Key, web, App, HttpServer, HttpResponse, Error};</span>
<span class="doccomment">/// use actix_session::{SessionMiddleware, storage::CookieSessionStore};</span>
<span class="doccomment">///</span>
<span class="doccomment">/// // The secret key would usually be read from a configuration file/environment variables.</span>
<span class="doccomment">/// fn get_secret_key() -&gt; Key {</span>
<span class="doccomment">/// # todo!()</span>
<span class="doccomment">/// // [...]</span>
<span class="doccomment">/// }</span>
<span class="doccomment">///</span>
<span class="doccomment">/// #[actix_web::main]</span>
<span class="doccomment">/// async fn main() -&gt; std::io::Result&lt;()&gt; {</span>
<span class="doccomment">/// let secret_key = get_secret_key();</span>
<span class="doccomment">/// HttpServer::new(move ||</span>
<span class="doccomment">/// App::new()</span>
<span class="doccomment">/// .wrap(SessionMiddleware::new(CookieSessionStore::default(), secret_key.clone()))</span>
<span class="doccomment">/// .default_service(web::to(|| HttpResponse::Ok())))</span>
<span class="doccomment">/// .bind((&quot;127.0.0.1&quot;, 8080))?</span>
<span class="doccomment">/// .run()</span>
<span class="doccomment">/// .await</span>
<span class="doccomment">/// }</span>
<span class="doccomment">/// ```</span>
<span class="doccomment">///</span>
<span class="doccomment">/// # Limitations</span>
<span class="doccomment">/// Cookies are subject to size limits - we require session keys to be shorter than 4096 bytes. This</span>
<span class="doccomment">/// translates into a limit on the maximum size of the session state when using cookies as storage</span>
<span class="doccomment">/// backend.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// The session cookie can always be inspected by end users via the developer tools exposed by their</span>
<span class="doccomment">/// browsers. We strongly recommend setting the policy to [`CookieContentSecurity::Private`] when</span>
<span class="doccomment">/// using cookies as storage backend.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// There is no way to invalidate a session before its natural expiry when using cookies as the</span>
<span class="doccomment">/// storage backend.</span>
<span class="doccomment">///</span>
<span class="doccomment">/// [`CookieContentSecurity::Private`]: crate::CookieContentSecurity::Private</span>
<span class="attribute">#[<span class="ident">cfg_attr</span>(<span class="ident">docsrs</span>, <span class="ident">doc</span>(<span class="ident">cfg</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">&quot;cookie-session&quot;</span>)))]</span>
<span class="attribute">#[<span class="ident">derive</span>(<span class="ident">Default</span>)]</span>
<span class="attribute">#[<span class="ident">non_exhaustive</span>]</span>
<span class="kw">pub</span> <span class="kw">struct</span> <span class="ident">CookieSessionStore</span>;
<span class="attribute">#[<span class="ident">async_trait::async_trait</span>(<span class="question-mark">?</span><span class="ident">Send</span>)]</span>
<span class="kw">impl</span> <span class="ident">SessionStore</span> <span class="kw">for</span> <span class="ident">CookieSessionStore</span> {
<span class="kw">async</span> <span class="kw">fn</span> <span class="ident">load</span>(<span class="kw-2">&amp;</span><span class="self">self</span>, <span class="ident">session_key</span>: <span class="kw-2">&amp;</span><span class="ident">SessionKey</span>) -&gt; <span class="prelude-ty">Result</span><span class="op">&lt;</span><span class="prelude-ty">Option</span><span class="op">&lt;</span><span class="ident">SessionState</span><span class="op">&gt;</span>, <span class="ident">LoadError</span><span class="op">&gt;</span> {
<span class="ident">serde_json::from_str</span>(<span class="ident">session_key</span>.<span class="ident">as_ref</span>())
.<span class="ident">map</span>(<span class="prelude-val">Some</span>)
.<span class="ident">map_err</span>(<span class="ident">anyhow::Error::new</span>)
.<span class="ident">map_err</span>(<span class="ident">LoadError::Deserialization</span>)
}
<span class="kw">async</span> <span class="kw">fn</span> <span class="ident">save</span>(
<span class="kw-2">&amp;</span><span class="self">self</span>,
<span class="ident">session_state</span>: <span class="ident">SessionState</span>,
<span class="ident">_ttl</span>: <span class="kw-2">&amp;</span><span class="ident">Duration</span>,
) -&gt; <span class="prelude-ty">Result</span><span class="op">&lt;</span><span class="ident">SessionKey</span>, <span class="ident">SaveError</span><span class="op">&gt;</span> {
<span class="kw">let</span> <span class="ident">session_key</span> <span class="op">=</span> <span class="ident">serde_json::to_string</span>(<span class="kw-2">&amp;</span><span class="ident">session_state</span>)
.<span class="ident">map_err</span>(<span class="ident">anyhow::Error::new</span>)
.<span class="ident">map_err</span>(<span class="ident">SaveError::Serialization</span>)<span class="question-mark">?</span>;
<span class="prelude-val">Ok</span>(<span class="ident">session_key</span>
.<span class="ident">try_into</span>()
.<span class="ident">map_err</span>(<span class="ident">Into::into</span>)
.<span class="ident">map_err</span>(<span class="ident">SaveError::Other</span>)<span class="question-mark">?</span>)
}
<span class="kw">async</span> <span class="kw">fn</span> <span class="ident">update</span>(
<span class="kw-2">&amp;</span><span class="self">self</span>,
<span class="ident">_session_key</span>: <span class="ident">SessionKey</span>,
<span class="ident">session_state</span>: <span class="ident">SessionState</span>,
<span class="ident">ttl</span>: <span class="kw-2">&amp;</span><span class="ident">Duration</span>,
) -&gt; <span class="prelude-ty">Result</span><span class="op">&lt;</span><span class="ident">SessionKey</span>, <span class="ident">UpdateError</span><span class="op">&gt;</span> {
<span class="self">self</span>.<span class="ident">save</span>(<span class="ident">session_state</span>, <span class="ident">ttl</span>)
.<span class="kw">await</span>
.<span class="ident">map_err</span>(<span class="op">|</span><span class="ident">err</span><span class="op">|</span> <span class="kw">match</span> <span class="ident">err</span> {
<span class="ident">SaveError::Serialization</span>(<span class="ident">err</span>) =&gt; <span class="ident">UpdateError::Serialization</span>(<span class="ident">err</span>),
<span class="ident">SaveError::Other</span>(<span class="ident">err</span>) =&gt; <span class="ident">UpdateError::Other</span>(<span class="ident">err</span>),
})
}
<span class="kw">async</span> <span class="kw">fn</span> <span class="ident">delete</span>(<span class="kw-2">&amp;</span><span class="self">self</span>, <span class="ident">_session_key</span>: <span class="kw-2">&amp;</span><span class="ident">SessionKey</span>) -&gt; <span class="prelude-ty">Result</span><span class="op">&lt;</span>(), <span class="ident">anyhow::Error</span><span class="op">&gt;</span> {
<span class="prelude-val">Ok</span>(())
}
}
<span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">test</span>)]</span>
<span class="kw">mod</span> <span class="ident">tests</span> {
<span class="kw">use</span> <span class="kw">super</span>::<span class="kw-2">*</span>;
<span class="kw">use</span> <span class="kw">crate</span>::{<span class="ident">storage::utils::generate_session_key</span>, <span class="ident">test_helpers::acceptance_test_suite</span>};
<span class="attribute">#[<span class="ident">actix_web::test</span>]</span>
<span class="kw">async</span> <span class="kw">fn</span> <span class="ident">test_session_workflow</span>() {
<span class="ident">acceptance_test_suite</span>(<span class="ident">CookieSessionStore::default</span>, <span class="bool-val">false</span>).<span class="kw">await</span>;
}
<span class="attribute">#[<span class="ident">actix_web::test</span>]</span>
<span class="kw">async</span> <span class="kw">fn</span> <span class="ident">loading_a_random_session_key_returns_deserialization_error</span>() {
<span class="kw">let</span> <span class="ident">store</span> <span class="op">=</span> <span class="ident">CookieSessionStore::default</span>();
<span class="kw">let</span> <span class="ident">session_key</span> <span class="op">=</span> <span class="ident">generate_session_key</span>();
<span class="macro">assert!</span>(<span class="macro">matches!</span>(
<span class="ident">store</span>.<span class="ident">load</span>(<span class="kw-2">&amp;</span><span class="ident">session_key</span>).<span class="kw">await</span>.<span class="ident">unwrap_err</span>(),
<span class="ident">LoadError::Deserialization</span>(<span class="kw">_</span>),
));
}
}
</code></pre></div>
</section><section id="search" class="content hidden"></section></div></main><div id="rustdoc-vars" data-root-path="../../../" data-current-crate="actix_session" data-themes="ayu,dark,light" data-resource-suffix="" data-rustdoc-version="1.61.0-nightly (58f11791a 2022-03-17)" ></div>
</body></html>