0
# Jetty HTTP
1

2
Jetty HTTP is the core HTTP protocol support library for Eclipse Jetty, providing comprehensive HTTP processing capabilities including header handling, parsing, generation, compliance validation, compression utilities, content management, and path mapping. It serves as the foundation for HTTP clients and servers with optimized performance and zero-copy buffer management.
3

4
## Package Information
5

6
- **Package Name**: org.eclipse.jetty:jetty-http
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.eclipse.jetty</groupId>
13
    <artifactId>jetty-http</artifactId>
14
    <version>12.0.21</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.eclipse.jetty.http.*;
22
import org.eclipse.jetty.http.pathmap.*;
23
import org.eclipse.jetty.http.compression.*;
24
import org.eclipse.jetty.http.content.*;
25
```
26

27
## Basic Usage
28

29
```java
30
import org.eclipse.jetty.http.*;
31

32
// Create and manipulate HTTP headers
33
MutableHttpFields headers = new MutableHttpFields();
34
headers.put(HttpHeader.CONTENT_TYPE, "application/json");
35
headers.put(HttpHeader.CACHE_CONTROL, "no-cache");
36

37
// Parse HTTP method and status
38
HttpMethod method = HttpMethod.fromString("POST");
39
int statusCode = HttpStatus.OK_200;
40

41
// Handle URIs
42
HttpURI uri = HttpURI.from("https://example.com/api/users?id=123");
43
String host = uri.getHost(); // "example.com"
44
String path = uri.getPath(); // "/api/users"
45
String query = uri.getQuery(); // "id=123"
46

47
// Parse cookies
48
MutableHttpFields cookieHeaders = new MutableHttpFields();
49
cookieHeaders.add(HttpHeader.COOKIE, "session=abc123; user=john");
50
CookieCutter parser = new CookieCutter();
51
parser.parseFields(cookieHeaders);
52
```
53

54
## Architecture
55

56
Jetty HTTP is organized around several key components:
57

58
- **Core HTTP Processing**: HTTP methods, status codes, headers, and protocol handling (`HttpMethod`, `HttpStatus`, `HttpField`, `HttpFields`)
59
- **Parsing and Generation**: HTTP message parsing and generation with compliance validation (`HttpParser`, `HttpGenerator`)
60
- **URI Handling**: Comprehensive URI parsing, validation, and manipulation (`HttpURI`, `UriCompliance`)
61
- **Content Management**: HTTP content handling with caching, compression, and virtual file systems (`HttpContent`, `HttpContent.Factory`)
62
- **Path Mapping**: Flexible path specification matching for routing and dispatch (`PathSpec`, `ServletPathSpec`, `PathMappings`)
63
- **Compression**: HPACK compression utilities for HTTP/2 header compression (`NBitIntegerEncoder`, `Huffman`)
64
- **Compliance**: Configurable HTTP, URI, and cookie compliance modes with violation tracking
65

66
## Capabilities
67

68
### HTTP Headers and Fields
69

70
Core HTTP header handling with optimized field collections, type-safe header enums, and efficient header value processing.
71

72
```java { .api }
73
// Header field creation and manipulation
74
HttpField field = new HttpField(HttpHeader.CONTENT_TYPE, "application/json");
75
MutableHttpFields fields = new MutableHttpFields();
76
HttpField result = fields.put(HttpHeader.CACHE_CONTROL, "no-cache");
77

78
// Header collections interface
79
interface HttpFields extends Iterable<HttpField> {
80
    int size();
81
    HttpField getField(String name);
82
    String get(HttpHeader header);
83
    boolean contains(String name, String value);
84
    Stream<HttpField> stream();
85
}
86
```
87

88
[HTTP Headers and Fields](./http-headers.md)
89

90
### HTTP Methods and Status
91

92
Standard HTTP method and status code handling with safety and idempotency checks, efficient parsing, and caching.
93

94
```java { .api }
95
// HTTP methods enumeration
96
enum HttpMethod {
97
    GET, POST, PUT, DELETE, HEAD, OPTIONS, TRACE, PATCH, CONNECT;
98
    
99
    boolean isSafe();
100
    boolean isIdempotent();
101
    ByteBuffer asBuffer();
102
    static HttpMethod fromString(String method);
103
}
104

105
// HTTP status codes and utilities
106
class HttpStatus {
107
    static final int OK_200 = 200;
108
    static final int NOT_FOUND_404 = 404;
109
    static final int INTERNAL_SERVER_ERROR_500 = 500;
110
    
111
    static String getMessage(int code);
112
    static boolean isInformational(int code);
113
    static boolean hasNoBody(int status);
114
}
115
```
116

117
[HTTP Methods and Status](./http-methods-status.md)
118

119
### URI Processing
120

121
Comprehensive URI parsing, validation, and manipulation with compliance checking and efficient immutable/mutable patterns.
122

123
```java { .api }
124
// URI interface and factories
125
interface HttpURI {
126
    String getScheme();
127
    String getHost();
128
    int getPort();
129
    String getPath();
130
    String getQuery();
131
    boolean isAbsolute();
132
    
133
    static HttpURI.Immutable from(String uri);
134
    static HttpURI.Mutable build(String uri);
135
}
136

137
// URI compliance validation
138
class UriCompliance {
139
    static final UriCompliance DEFAULT;
140
    static final UriCompliance LEGACY;
141
    boolean allows(Violation violation);
142
}
143
```
144

145
[URI Processing](./uri-processing.md)
146

147
### HTTP Parsing and Generation
148

149
High-performance HTTP message parsing and generation with configurable compliance modes and efficient buffer management.
150

151
```java { .api }
152
// HTTP parsing
153
class HttpParser {
154
    HttpParser(RequestHandler requestHandler);
155
    HttpParser(ResponseHandler responseHandler);
156
    boolean parseNext(ByteBuffer buffer);
157
    boolean isComplete();
158
    void reset();
159
}
160

161
// HTTP generation
162
class HttpGenerator {
163
    Result generateResponse(MetaData.Response info, boolean head, 
164
                          ByteBuffer header, ByteBuffer chunk, 
165
                          ByteBuffer content, boolean last);
166
    boolean isEnd();
167
    void reset();
168
}
169
```
170

171
[HTTP Parsing and Generation](./http-parsing-generation.md)
172

173
### Cookie Handling
174

175
Complete cookie parsing and management with RFC compliance support and attribute handling.
176

177
```java { .api }
178
// Cookie interface
179
interface HttpCookie {
180
    String getName();
181
    String getValue();
182
    String getDomain();
183
    String getPath();
184
    boolean isSecure();
185
    boolean isHttpOnly();
186
    SameSite getSameSite();
187
    
188
    static HttpCookie from(String name, String value);
189
}
190

191
// Cookie parsing
192
interface CookieParser {
193
    void parseField(HttpField field);
194
    void parseFields(HttpFields fields);
195
}
196
```
197

198
[Cookie Handling](./cookie-handling.md)
199

200
### Multi-Part Processing
201

202
Multi-part content handling for form data, file uploads, and byte ranges with async processing support.
203

204
```java { .api }
205
// Multi-part content processing
206
class MultiPart {
207
    String getBoundary();
208
    List<Part> getParts();
209
    Part getPart(String name);
210
    
211
    interface Part {
212
        String getName();
213
        String getFileName();
214
        HttpFields getHeaders();
215
        Content.Source getContentSource();
216
    }
217
}
218

219
// Form data processing
220
class MultiPartFormData {
221
    CompletableFuture<Parts> parse(Content.Source source);
222
    Parts from(Content.Source source);
223
}
224
```
225

226
[Multi-Part Processing](./multipart-processing.md)
227

228
### Content Management
229

230
HTTP content handling with factory patterns, caching, compression support, and virtual file systems.
231

232
```java { .api }
233
// Content interface
234
interface HttpContent {
235
    HttpField getContentType();
236
    HttpField getContentLength();
237
    HttpField getLastModified();
238
    HttpField getETag();
239
    ByteBuffer getByteBuffer();
240
    void release();
241
    
242
    interface Factory {
243
        HttpContent getContent(String path);
244
    }
245
}
246

247
// Content factories
248
class ResourceHttpContentFactory implements HttpContent.Factory;
249
class CachingHttpContentFactory implements HttpContent.Factory;
250
class VirtualHttpContentFactory implements HttpContent.Factory;
251
```
252

253
[Content Management](./content-management.md)
254

255
### Path Mapping
256

257
Flexible path specification matching for routing and dispatch with support for servlet-style, regex, and URI template patterns.
258

259
```java { .api }
260
// Path specification interface
261
interface PathSpec extends Comparable<PathSpec> {
262
    String getDeclaration();
263
    boolean matches(String path);
264
    MatchedPath matched(String path);
265
    String getPathInfo(String path);
266
}
267

268
// Path mappings collection
269
class PathMappings<E> extends AbstractMap<PathSpec, E> {
270
    MappedResource<E> getMatched(String path);
271
    List<MappedResource<E>> getMatches(String path);
272
    boolean put(PathSpec pathSpec, E resource);
273
}
274

275
// Servlet-style path specifications
276
class ServletPathSpec extends AbstractPathSpec {
277
    ServletPathSpec(String servletPathSpec);
278
}
279
```
280

281
[Path Mapping](./path-mapping.md)
282

283
### Compression Utilities
284

285
HPACK compression utilities for HTTP/2 header compression including N-bit integer encoding and Huffman coding.
286

287
```java { .api }
288
// N-bit integer encoding/decoding
289
class NBitIntegerEncoder {
290
    static int octetsNeeded(int prefix, long value);
291
    static void encode(ByteBuffer buffer, int prefix, long value);
292
}
293

294
class NBitIntegerDecoder {
295
    void setPrefix(int prefix);
296
    int decodeInt(ByteBuffer buffer);
297
    long decodeLong(ByteBuffer buffer);
298
    void reset();
299
}
300

301
// Huffman coding
302
class Huffman {
303
    // Huffman encoding/decoding utilities
304
}
305
```
306

307
[Compression Utilities](./compression-utilities.md)
308

309
## Common Types
310

311
```java { .api }
312
// HTTP version enumeration
313
enum HttpVersion {
314
    HTTP_0_9, HTTP_1_0, HTTP_1_1, HTTP_2_0, HTTP_3_0;
315
    String asString();
316
    int getVersion();
317
}
318

319
// HTTP scheme enumeration  
320
enum HttpScheme {
321
    HTTP, HTTPS, WS, WSS;
322
    String asString();
323
    int getDefaultPort();
324
}
325

326
// Metadata for requests and responses
327
class MetaData implements Iterable<HttpField> {
328
    HttpURI getHttpURI();
329
    HttpVersion getHttpVersion();
330
    HttpFields getHttpFields();
331
    
332
    static class Request extends MetaData;
333
    static class Response extends MetaData;
334
}
335

336
// Compliance violation handling
337
interface ComplianceViolation {
338
    interface Listener {
339
        void onComplianceViolation(Mode mode, ComplianceViolation violation, String details);
340
    }
341
    
342
    enum Mode { COMPLIANCE, LEGACY, CUSTOM }
343
}
344

345
// Content processing interface
346
interface Content {
347
    interface Source {
348
        // Content source for streaming processing
349
    }
350
    
351
    interface Chunk {
352
        ByteBuffer getByteBuffer();
353
        boolean isLast();
354
    }
355
}
356

357
// Exception types
358
class BadMessageException extends HttpException.RuntimeException;
359
class ComplianceViolationException extends IllegalArgumentException;
360
class EncodingException extends Exception;
361
```