0
# Cookie Handling
1

2
Complete cookie parsing and management with RFC compliance support, attribute handling, and efficient parsing for both Cookie and Set-Cookie headers.
3

4
## Capabilities
5

6
### HttpCookie Interface
7

8
Core cookie representation with attributes and builder pattern.
9

10
```java { .api }
11
/**
12
 * HTTP cookie representation with attributes
13
 */
14
interface HttpCookie {
15
    /** Get cookie name */
16
    String getName();
17
    
18
    /** Get cookie value */
19
    String getValue();
20
    
21
    /** Get cookie version (0 for Netscape, 1 for RFC 2965) */
22
    int getVersion();
23
    
24
    /** Get cookie domain attribute */
25
    String getDomain();
26
    
27
    /** Get cookie path attribute */
28
    String getPath();
29
    
30
    /** Get cookie comment (RFC 2965) */
31
    String getComment();
32
    
33
    /** Get max age in seconds (-1 for session cookie) */
34
    long getMaxAge();
35
    
36
    /** Check if cookie has Secure attribute */
37
    boolean isSecure();
38
    
39
    /** Check if cookie has HttpOnly attribute */
40
    boolean isHttpOnly();
41
    
42
    /** Get SameSite attribute */
43
    SameSite getSameSite();
44
    
45
    /** Get all cookie attributes as map */
46
    Map<String, String> getAttributes();
47
    
48
    /** Create simple cookie with name and value */
49
    static HttpCookie from(String name, String value);
50
    
51
    /** Create cookie builder */
52
    static HttpCookie build(String name, String value);
53
    
54
    /**
55
     * SameSite attribute values
56
     */
57
    enum SameSite {
58
        /** No SameSite restriction */
59
        NONE("None"),
60
        
61
        /** Lax SameSite policy */
62
        LAX("Lax"),
63
        
64
        /** Strict SameSite policy */
65
        STRICT("Strict");
66
        
67
        /** Get attribute value string */
68
        String getAttributeValue();
69
    }
70
}
71
```
72

73
### CookieParser Interface
74

75
Cookie header parsing interface for Cookie headers.
76

77
```java { .api }
78
/**
79
 * Interface for parsing Cookie headers
80
 */
81
interface CookieParser {
82
    /** Parse single cookie field */
83
    void parseField(HttpField field);
84
    
85
    /** Parse multiple cookie fields */
86
    void parseFields(HttpFields fields);
87
}
88
```
89

90
### CookieCutter Class
91

92
Standard cookie parser implementation with compliance support.
93

94
```java { .api }
95
/**
96
 * Standard cookie parser implementation
97
 */
98
class CookieCutter implements CookieParser {
99
    /** Create parser with default compliance */
100
    CookieCutter();
101
    
102
    /** Create parser with specific compliance and violation listener */
103
    CookieCutter(CookieCompliance compliance, 
104
                ComplianceViolation.Listener complianceListener);
105
    
106
    /** Parse cookie field and extract cookies */
107
    void parseField(HttpField field);
108
    
109
    /** Parse multiple cookie fields */
110
    void parseFields(HttpFields fields);
111
    
112
    /** Get parsed cookies */
113
    HttpCookie[] getCookies();
114
    
115
    /** Reset parser state */
116
    void reset();
117
    
118
    /** Set cookie compliance mode */
119
    void setCookieCompliance(CookieCompliance compliance);
120
    
121
    /** Get current compliance mode */
122
    CookieCompliance getCookieCompliance();
123
}
124
```
125

126
### Set-Cookie Parsers
127

128
Specialized parsers for Set-Cookie headers with different RFC compliance.
129

130
```java { .api }
131
/**
132
 * RFC 6265 Set-Cookie parser
133
 */
134
class RFC6265CookieParser implements CookieParser {
135
    /** Create RFC 6265 compliant parser */
136
    RFC6265CookieParser();
137
    
138
    /** Create parser with compliance and violation listener */
139
    RFC6265CookieParser(CookieCompliance compliance,
140
                       ComplianceViolation.Listener listener);
141
    
142
    /** Parse Set-Cookie field */
143
    void parseField(HttpField field);
144
    
145
    /** Get parsed cookie */
146
    HttpCookie getCookie();
147
}
148

149
/**
150
 * Legacy Set-Cookie parser with more lenient parsing
151
 */
152
class SetCookieParser implements CookieParser {
153
    /** Create lenient Set-Cookie parser */
154
    SetCookieParser();
155
    
156
    /** Create parser with compliance settings */
157
    SetCookieParser(CookieCompliance compliance,
158
                   ComplianceViolation.Listener listener);
159
    
160
    /** Parse Set-Cookie field */
161
    void parseField(HttpField field);
162
    
163
    /** Get parsed cookie */
164
    HttpCookie getCookie();
165
}
166
```
167

168
### CookieCompliance Class
169

170
Cookie compliance modes and violation handling.
171

172
```java { .api }
173
/**
174
 * Cookie compliance modes and validation
175
 */
176
class CookieCompliance {
177
    /** Strict RFC 6265 compliance */
178
    static final CookieCompliance RFC6265;
179
    
180
    /** RFC 2965 compatibility mode */
181
    static final CookieCompliance RFC2965;
182
    
183
    /** Legacy Netscape cookie compatibility */
184
    static final CookieCompliance LEGACY;
185
    
186
    /** Check if violation is allowed in this compliance mode */
187
    boolean allows(Violation violation);
188
    
189
    /** Get set of allowed violations */
190
    Set<Violation> getAllowed();
191
    
192
    /** Get compliance mode name */
193
    String getName();
194
    
195
    /**
196
     * Cookie compliance violations
197
     */
198
    enum Violation {
199
        /** Invalid cookie name characters */
200
        INVALID_COOKIE_NAME,
201
        
202
        /** Invalid cookie value characters */
203
        INVALID_COOKIE_VALUE,
204
        
205
        /** Reserved cookie name (like $Path, $Domain) */
206
        RESERVED_NAMES_NOT_DOLLAR_PREFIXED,
207
        
208
        /** Attribute without value */
209
        ATTRIBUTE_WITHOUT_VALUE,
210
        
211
        /** Invalid attribute name */
212
        INVALID_ATTRIBUTE,
213
        
214
        /** Comma separator in cookie value */
215
        COMMA_SEPARATOR;
216
    }
217
}
218
```
219

220
### HttpCookieStore Interface
221

222
Cookie storage and management interface.
223

224
```java { .api }
225
/**
226
 * Cookie storage and management interface
227
 */
228
interface HttpCookieStore {
229
    /** Add cookie to store */
230
    void add(HttpURI uri, HttpCookie cookie);
231
    
232
    /** Get cookies for URI */
233
    List<HttpCookie> get(HttpURI uri);
234
    
235
    /** Remove cookie from store */
236
    boolean remove(HttpURI uri, HttpCookie cookie);
237
    
238
    /** Remove all cookies */
239
    boolean removeAll();
240
    
241
    /** Get all cookies in store */
242
    List<HttpCookie> getCookies();
243
    
244
    /** Get URIs with cookies */
245
    List<HttpURI> getURIs();
246
}
247
```
248

249
### CookieCache Class
250

251
Efficient cookie caching for frequently used cookies.
252

253
```java { .api }
254
/**
255
 * Cache for frequently used cookies
256
 */
257
class CookieCache {
258
    /** Create cache with default size */
259
    CookieCache();
260
    
261
    /** Create cache with specific size */
262
    CookieCache(int size);
263
    
264
    /** Get cached cookie by name and value */
265
    HttpCookie get(String name, String value);
266
    
267
    /** Put cookie in cache */
268
    void put(HttpCookie cookie);
269
    
270
    /** Clear cache */
271
    void clear();
272
    
273
    /** Get cache size */
274
    int size();
275
}
276
```
277

278
**Usage Examples:**
279

280
```java
281
import org.eclipse.jetty.http.*;
282

283
// Parse Cookie header
284
MutableHttpFields headers = new MutableHttpFields();
285
headers.add(HttpHeader.COOKIE, "session=abc123; user=john; theme=dark");
286

287
CookieCutter parser = new CookieCutter();
288
parser.parseFields(headers);
289

290
HttpCookie[] cookies = parser.getCookies();
291
for (HttpCookie cookie : cookies) {
292
    String name = cookie.getName();      // "session", "user", "theme"
293
    String value = cookie.getValue();    // "abc123", "john", "dark"
294
}
295

296
// Parse Set-Cookie header with RFC 6265 compliance
297
HttpField setCookieField = new HttpField(HttpHeader.SET_COOKIE, 
298
    "sessionId=xyz789; Path=/; Domain=.example.com; Secure; HttpOnly; SameSite=Strict; Max-Age=3600");
299

300
RFC6265CookieParser setCookieParser = new RFC6265CookieParser();
301
setCookieParser.parseField(setCookieField);
302

303
HttpCookie cookie = setCookieParser.getCookie();
304
String name = cookie.getName();          // "sessionId"
305
String value = cookie.getValue();        // "xyz789"
306
String domain = cookie.getDomain();      // ".example.com"
307
String path = cookie.getPath();          // "/"
308
boolean secure = cookie.isSecure();      // true
309
boolean httpOnly = cookie.isHttpOnly();  // true
310
HttpCookie.SameSite sameSite = cookie.getSameSite(); // STRICT
311
long maxAge = cookie.getMaxAge();        // 3600
312

313
// Create cookies programmatically
314
HttpCookie simpleCookie = HttpCookie.from("username", "alice");
315

316
HttpCookie complexCookie = HttpCookie.build("auth", "token123")
317
    .domain(".example.com")
318
    .path("/api")
319
    .secure(true)
320
    .httpOnly(true)
321
    .sameSite(HttpCookie.SameSite.LAX)
322
    .maxAge(7200)
323
    .build();
324

325
// Cookie compliance handling
326
CookieCompliance strict = CookieCompliance.RFC6265;
327
CookieCompliance lenient = CookieCompliance.LEGACY;
328

329
ComplianceViolation.Listener violationListener = 
330
    (mode, violation, details) -> {
331
        System.out.println("Cookie violation: " + violation + " - " + details);
332
    };
333

334
CookieCutter compliantParser = new CookieCutter(strict, violationListener);
335

336
// Cookie storage
337
HttpCookieStore cookieStore = new HttpCookieStore() {
338
    private final Map<String, List<HttpCookie>> cookies = new HashMap<>();
339
    
340
    @Override
341
    public void add(HttpURI uri, HttpCookie cookie) {
342
        cookies.computeIfAbsent(uri.getHost(), k -> new ArrayList<>()).add(cookie);
343
    }
344
    
345
    @Override
346
    public List<HttpCookie> get(HttpURI uri) {
347
        return cookies.getOrDefault(uri.getHost(), Collections.emptyList());
348
    }
349
    
350
    // ... implement other methods
351
};
352

353
// Add cookies to store
354
HttpURI uri = HttpURI.from("https://example.com/api");
355
cookieStore.add(uri, HttpCookie.from("session", "abc123"));
356

357
// Retrieve cookies for URI
358
List<HttpCookie> uriCookies = cookieStore.get(uri);
359

360
// Cookie caching for performance
361
CookieCache cache = new CookieCache(100);
362
cache.put(HttpCookie.from("frequent", "value"));
363

364
HttpCookie cached = cache.get("frequent", "value");
365

366
// Working with cookie attributes
367
Map<String, String> attributes = cookie.getAttributes();
368
String customAttr = attributes.get("CustomAttribute");
369

370
// Handle different SameSite values
371
switch (cookie.getSameSite()) {
372
    case STRICT:
373
        // Handle strict same-site policy
374
        break;
375
    case LAX:
376
        // Handle lax same-site policy
377
        break;
378
    case NONE:
379
        // Handle no same-site restriction (requires Secure)
380
        break;
381
}
382

383
// Check for session vs persistent cookies
384
if (cookie.getMaxAge() == -1) {
385
    // Session cookie (expires when browser closes)
386
} else {
387
    // Persistent cookie with expiration
388
}
389
```