cookie/builder.rs
1use std::borrow::Cow;
2
3use crate::{Cookie, SameSite, Expiration};
4
5/// Structure that follows the builder pattern for building `Cookie` structs.
6///
7/// To construct a cookie:
8///
9/// 1. Call [`Cookie::build`] to start building.
10/// 2. Use any of the builder methods to set fields in the cookie.
11/// 3. Call [`CookieBuilder::finish()`] to retrieve the built cookie.
12///
13/// # Example
14///
15/// ```rust
16/// # extern crate cookie;
17/// extern crate time;
18///
19/// use cookie::Cookie;
20/// use time::Duration;
21///
22/// # fn main() {
23/// let cookie: Cookie = Cookie::build("name", "value")
24/// .domain("www.rust-lang.org")
25/// .path("/")
26/// .secure(true)
27/// .http_only(true)
28/// .max_age(Duration::days(1))
29/// .finish();
30/// # }
31/// ```
32#[derive(Debug, Clone)]
33pub struct CookieBuilder<'c> {
34 /// The cookie being built.
35 cookie: Cookie<'c>,
36}
37
38impl<'c> CookieBuilder<'c> {
39 /// Creates a new `CookieBuilder` instance from the given name and value.
40 ///
41 /// This method is typically called indirectly via [`Cookie::build()`].
42 ///
43 /// # Example
44 ///
45 /// ```rust
46 /// use cookie::Cookie;
47 ///
48 /// let c = Cookie::build("foo", "bar").finish();
49 /// assert_eq!(c.name_value(), ("foo", "bar"));
50 /// ```
51 pub fn new<N, V>(name: N, value: V) -> Self
52 where N: Into<Cow<'c, str>>,
53 V: Into<Cow<'c, str>>
54 {
55 CookieBuilder { cookie: Cookie::new(name, value) }
56 }
57
58 /// Sets the `expires` field in the cookie being built.
59 ///
60 /// # Example
61 ///
62 /// ```rust
63 /// # extern crate cookie;
64 /// extern crate time;
65 /// use time::OffsetDateTime;
66 ///
67 /// use cookie::{Cookie, Expiration};
68 ///
69 /// # fn main() {
70 /// let c = Cookie::build("foo", "bar")
71 /// .expires(OffsetDateTime::now())
72 /// .finish();
73 ///
74 /// assert!(c.expires().is_some());
75 ///
76 /// let c = Cookie::build("foo", "bar")
77 /// .expires(None)
78 /// .finish();
79 ///
80 /// assert_eq!(c.expires(), Some(Expiration::Session));
81 /// # }
82 /// ```
83 #[inline]
84 pub fn expires<E: Into<Expiration>>(mut self, when: E) -> Self {
85 self.cookie.set_expires(when);
86 self
87 }
88
89 /// Sets the `max_age` field in the cookie being built.
90 ///
91 /// # Example
92 ///
93 /// ```rust
94 /// # extern crate cookie;
95 /// extern crate time;
96 /// use time::Duration;
97 ///
98 /// use cookie::Cookie;
99 ///
100 /// # fn main() {
101 /// let c = Cookie::build("foo", "bar")
102 /// .max_age(Duration::minutes(30))
103 /// .finish();
104 ///
105 /// assert_eq!(c.max_age(), Some(Duration::seconds(30 * 60)));
106 /// # }
107 /// ```
108 #[inline]
109 pub fn max_age(mut self, value: time::Duration) -> Self {
110 self.cookie.set_max_age(value);
111 self
112 }
113
114 /// Sets the `domain` field in the cookie being built.
115 ///
116 /// # Example
117 ///
118 /// ```rust
119 /// use cookie::Cookie;
120 ///
121 /// let c = Cookie::build("foo", "bar")
122 /// .domain("www.rust-lang.org")
123 /// .finish();
124 ///
125 /// assert_eq!(c.domain(), Some("www.rust-lang.org"));
126 /// ```
127 pub fn domain<D: Into<Cow<'c, str>>>(mut self, value: D) -> Self {
128 self.cookie.set_domain(value);
129 self
130 }
131
132 /// Sets the `path` field in the cookie being built.
133 ///
134 /// # Example
135 ///
136 /// ```rust
137 /// use cookie::Cookie;
138 ///
139 /// let c = Cookie::build("foo", "bar")
140 /// .path("/")
141 /// .finish();
142 ///
143 /// assert_eq!(c.path(), Some("/"));
144 /// ```
145 pub fn path<P: Into<Cow<'c, str>>>(mut self, path: P) -> Self {
146 self.cookie.set_path(path);
147 self
148 }
149
150 /// Sets the `secure` field in the cookie being built.
151 ///
152 /// # Example
153 ///
154 /// ```rust
155 /// use cookie::Cookie;
156 ///
157 /// let c = Cookie::build("foo", "bar")
158 /// .secure(true)
159 /// .finish();
160 ///
161 /// assert_eq!(c.secure(), Some(true));
162 /// ```
163 #[inline]
164 pub fn secure(mut self, value: bool) -> Self {
165 self.cookie.set_secure(value);
166 self
167 }
168
169 /// Sets the `http_only` field in the cookie being built.
170 ///
171 /// # Example
172 ///
173 /// ```rust
174 /// use cookie::Cookie;
175 ///
176 /// let c = Cookie::build("foo", "bar")
177 /// .http_only(true)
178 /// .finish();
179 ///
180 /// assert_eq!(c.http_only(), Some(true));
181 /// ```
182 #[inline]
183 pub fn http_only(mut self, value: bool) -> Self {
184 self.cookie.set_http_only(value);
185 self
186 }
187
188 /// Sets the `same_site` field in the cookie being built.
189 ///
190 /// # Example
191 ///
192 /// ```rust
193 /// use cookie::{Cookie, SameSite};
194 ///
195 /// let c = Cookie::build("foo", "bar")
196 /// .same_site(SameSite::Strict)
197 /// .finish();
198 ///
199 /// assert_eq!(c.same_site(), Some(SameSite::Strict));
200 /// ```
201 #[inline]
202 pub fn same_site(mut self, value: SameSite) -> Self {
203 self.cookie.set_same_site(value);
204 self
205 }
206
207 /// Makes the cookie being built 'permanent' by extending its expiration and
208 /// max age 20 years into the future.
209 ///
210 /// # Example
211 ///
212 /// ```rust
213 /// # extern crate cookie;
214 /// extern crate time;
215 ///
216 /// use cookie::Cookie;
217 /// use time::Duration;
218 ///
219 /// # fn main() {
220 /// let c = Cookie::build("foo", "bar")
221 /// .permanent()
222 /// .finish();
223 ///
224 /// assert_eq!(c.max_age(), Some(Duration::days(365 * 20)));
225 /// # assert!(c.expires().is_some());
226 /// # }
227 /// ```
228 #[inline]
229 pub fn permanent(mut self) -> Self {
230 self.cookie.make_permanent();
231 self
232 }
233
234 /// Finishes building and returns the built `Cookie`.
235 ///
236 /// # Example
237 ///
238 /// ```rust
239 /// use cookie::Cookie;
240 ///
241 /// let c = Cookie::build("foo", "bar")
242 /// .domain("crates.io")
243 /// .path("/")
244 /// .finish();
245 ///
246 /// assert_eq!(c.name_value(), ("foo", "bar"));
247 /// assert_eq!(c.domain(), Some("crates.io"));
248 /// assert_eq!(c.path(), Some("/"));
249 /// ```
250 #[inline]
251 pub fn finish(self) -> Cookie<'c> {
252 self.cookie
253 }
254}