0
# Header Management
1

2
Filter for setting, adding, or modifying HTTP headers on responses with flexible configuration syntax. The HeaderFilter provides a simple way to manipulate HTTP headers based on include/exclude patterns.
3

4
## Capabilities
5

6
### HeaderFilter
7

8
Filter that extends IncludeExcludeBasedFilter to provide HTTP header manipulation capabilities.
9

10
```java { .api }
11
/**
12
 * Filter for setting or adding headers to HTTP responses.
13
 * Extends IncludeExcludeBasedFilter to support path, MIME type, and method filtering.
14
 */
15
public class HeaderFilter extends IncludeExcludeBasedFilter {
16
    /**
17
     * Initialize the filter with configuration parameters
18
     * @param filterConfig Filter configuration containing headerConfig parameter
19
     * @throws ServletException if configuration is invalid
20
     */
21
    public void init(FilterConfig filterConfig) throws ServletException;
22
    
23
    /**
24
     * Process the request and apply header modifications to the response
25
     * @param request The servlet request
26
     * @param response The servlet response  
27
     * @param chain The filter chain
28
     * @throws IOException if I/O error occurs
29
     * @throws ServletException if servlet error occurs
30
     */
31
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) 
32
        throws IOException, ServletException;
33
    
34
    /**
35
     * Get string representation of the filter configuration
36
     * @return String describing the filter setup
37
     */
38
    public String toString();
39
}
40
```
41

42
## Configuration
43

44
### headerConfig Parameter
45

46
The primary configuration parameter that defines header operations.
47

48
**Format**: `[action] [header name]: [header value]`
49

50
**Actions**:
51
- `set` - Set header value (replaces existing)
52
- `add` - Add header value (allows multiple values)
53
- `setDate` - Set header with date formatting
54
- `addDate` - Add header with date formatting
55

56
**Syntax**: Comma-separated list of header operations.
57

58
### Inherited Configuration
59

60
HeaderFilter inherits all configuration options from IncludeExcludeBasedFilter:
61

62
- **includedPaths**: CSV of path specs to include
63
- **excludedPaths**: CSV of path specs to exclude  
64
- **includedMimeTypes**: CSV of MIME types to include
65
- **excludedMimeTypes**: CSV of MIME types to exclude
66
- **includedHttpMethods**: CSV of HTTP methods to include
67
- **excludedHttpMethods**: CSV of HTTP methods to exclude
68

69
## Usage Examples
70

71
### Basic Header Setting
72

73
```xml
74
<!-- Web.xml configuration -->
75
<filter>
76
    <filter-name>HeaderFilter</filter-name>
77
    <filter-class>org.eclipse.jetty.ee10.servlets.HeaderFilter</filter-class>
78
    <init-param>
79
        <param-name>headerConfig</param-name>
80
        <param-value>set X-Frame-Options: DENY, set X-Content-Type-Options: nosniff</param-value>
81
    </init-param>
82
</filter>
83
<filter-mapping>
84
    <filter-name>HeaderFilter</filter-name>
85
    <url-pattern>/*</url-pattern>
86
</filter-mapping>
87
```
88

89
### Security Headers Configuration
90

91
```xml
92
<filter>
93
    <filter-name>SecurityHeaderFilter</filter-name>
94
    <filter-class>org.eclipse.jetty.ee10.servlets.HeaderFilter</filter-class>
95
    <init-param>
96
        <param-name>headerConfig</param-name>
97
        <param-value>
98
            set X-Frame-Options: SAMEORIGIN,
99
            set X-Content-Type-Options: nosniff,
100
            set X-XSS-Protection: 1; mode=block,
101
            set Referrer-Policy: strict-origin-when-cross-origin,
102
            set Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline',
103
            set Strict-Transport-Security: max-age=31536000; includeSubDomains
104
        </param-value>
105
    </init-param>
106
</filter>
107
```
108

109
### Cache Control Headers
110

111
```xml
112
<filter>
113
    <filter-name>CacheHeaderFilter</filter-name>
114
    <filter-class>org.eclipse.jetty.ee10.servlets.HeaderFilter</filter-class>
115
    <init-param>
116
        <param-name>headerConfig</param-name>
117
        <param-value>
118
            set Cache-Control: public, max-age=3600,
119
            set Expires: Thu, 01 Jan 2025 00:00:00 GMT,
120
            add Vary: Accept-Encoding
121
        </param-value>
122
    </init-param>
123
    <!-- Only apply to static resources -->
124
    <init-param>
125
        <param-name>includedPaths</param-name>
126
        <param-value>/static/*,/assets/*,*.css,*.js,*.png,*.jpg,*.gif</param-value>
127
    </init-param>
128
</filter>
129
```
130

131
### Date Headers
132

133
```xml
134
<filter>
135
    <filter-name>DateHeaderFilter</filter-name>
136
    <filter-class>org.eclipse.jetty.ee10.servlets.HeaderFilter</filter-class>
137
    <init-param>
138
        <param-name>headerConfig</param-name>
139
        <param-value>
140
            setDate Last-Modified: 2024-01-01T00:00:00Z,
141
            addDate X-Generated: now
142
        </param-value>
143
    </init-param>
144
</filter>
145
```
146

147
### API Response Headers
148

149
```xml
150
<filter>
151
    <filter-name>ApiHeaderFilter</filter-name>
152
    <filter-class>org.eclipse.jetty.ee10.servlets.HeaderFilter</filter-class>
153
    <init-param>
154
        <param-name>headerConfig</param-name>
155
        <param-value>
156
            set X-API-Version: v1.2.0,
157
            add X-Powered-By: Jetty,
158
            set Access-Control-Max-Age: 3600
159
        </param-value>
160
    </init-param>
161
    <!-- Only apply to API endpoints -->
162
    <init-param>
163
        <param-name>includedPaths</param-name>
164
        <param-value>/api/*</param-value>
165
    </init-param>
166
    <!-- Only for JSON responses -->
167
    <init-param>
168
        <param-name>includedMimeTypes</param-name>
169
        <param-value>application/json</param-value>
170
    </init-param>
171
</filter>
172
```
173

174
### Conditional Headers by HTTP Method
175

176
```xml
177
<filter>
178
    <filter-name>PostHeaderFilter</filter-name>
179
    <filter-class>org.eclipse.jetty.ee10.servlets.HeaderFilter</filter-class>
180
    <init-param>
181
        <param-name>headerConfig</param-name>
182
        <param-value>
183
            set X-CSRF-Protection: enabled,
184
            set X-Request-ID: auto-generated
185
        </param-value>
186
    </init-param>
187
    <!-- Only apply to POST and PUT requests -->
188
    <init-param>
189
        <param-name>includedHttpMethods</param-name>
190
        <param-value>POST,PUT</param-value>
191
    </init-param>
192
</filter>
193
```
194

195
### Complex Filter Chain
196

197
```xml
198
<!-- Multiple header filters for different purposes -->
199

200
<!-- Global security headers -->
201
<filter>
202
    <filter-name>GlobalSecurityHeaders</filter-name>
203
    <filter-class>org.eclipse.jetty.ee10.servlets.HeaderFilter</filter-class>
204
    <init-param>
205
        <param-name>headerConfig</param-name>
206
        <param-value>
207
            set X-Frame-Options: SAMEORIGIN,
208
            set X-Content-Type-Options: nosniff
209
        </param-value>
210
    </init-param>
211
</filter>
212

213
<!-- API-specific headers -->
214
<filter>
215
    <filter-name>ApiHeaders</filter-name>
216
    <filter-class>org.eclipse.jetty.ee10.servlets.HeaderFilter</filter-class>
217
    <init-param>
218
        <param-name>headerConfig</param-name>
219
        <param-value>
220
            set X-API-Version: v2.1,
221
            add X-Rate-Limit-Window: 3600
222
        </param-value>
223
    </init-param>
224
    <init-param>
225
        <param-name>includedPaths</param-name>
226
        <param-value>/api/*</param-value>
227
    </init-param>
228
</filter>
229

230
<!-- Static resource headers -->
231
<filter>
232
    <filter-name>StaticResourceHeaders</filter-name>
233
    <filter-class>org.eclipse.jetty.ee10.servlets.HeaderFilter</filter-class>
234
    <init-param>
235
        <param-name>headerConfig</param-name>
236
        <param-value>
237
            set Cache-Control: public, max-age=86400,
238
            add Vary: Accept-Encoding
239
        </param-value>
240
    </init-param>
241
    <init-param>
242
        <param-name>includedPaths</param-name>
243
        <param-value>*.css,*.js,*.png,*.jpg,*.gif,*.ico</param-value>
244
    </init-param>
245
</filter>
246

247
<!-- Filter mappings -->
248
<filter-mapping>
249
    <filter-name>GlobalSecurityHeaders</filter-name>
250
    <url-pattern>/*</url-pattern>
251
</filter-mapping>
252
<filter-mapping>
253
    <filter-name>ApiHeaders</filter-name>  
254
    <url-pattern>/api/*</url-pattern>
255
</filter-mapping>
256
<filter-mapping>
257
    <filter-name>StaticResourceHeaders</filter-name>
258
    <url-pattern>/*</url-pattern>
259
</filter-mapping>
260
```
261

262
### Programmatic Configuration
263

264
```java
265
import org.eclipse.jetty.ee10.servlets.HeaderFilter;
266
import jakarta.servlet.FilterConfig;
267
import jakarta.servlet.ServletContext;
268

269
public class HeaderFilterConfig {
270
    public static void configureSecurityHeaders(ServletContext context) {
271
        FilterRegistration.Dynamic headerFilter = context.addFilter("SecurityHeaders", 
272
                                                                    HeaderFilter.class);
273
        
274
        // Security headers configuration
275
        String securityHeaders = String.join(",", 
276
            "set X-Frame-Options: DENY",
277
            "set X-Content-Type-Options: nosniff", 
278
            "set X-XSS-Protection: 1; mode=block",
279
            "set Referrer-Policy: strict-origin-when-cross-origin",
280
            "set Content-Security-Policy: default-src 'self'"
281
        );
282
        
283
        headerFilter.setInitParameter("headerConfig", securityHeaders);
284
        headerFilter.addMappingForUrlPatterns(null, false, "/*");
285
    }
286
    
287
    public static void configureCacheHeaders(ServletContext context) {
288
        FilterRegistration.Dynamic cacheFilter = context.addFilter("CacheHeaders", 
289
                                                                   HeaderFilter.class);
290
        
291
        String cacheHeaders = String.join(",",
292
            "set Cache-Control: public, max-age=3600",
293
            "add Vary: Accept-Encoding, Accept"
294
        );
295
        
296
        cacheFilter.setInitParameter("headerConfig", cacheHeaders);
297
        cacheFilter.setInitParameter("includedPaths", "/static/*,*.css,*.js");
298
        cacheFilter.addMappingForUrlPatterns(null, false, "/*");
299
    }
300
}
301
```
302

303
## Header Action Details
304

305
### set Action
306
Replaces any existing header with the specified name.
307

308
```
309
set X-Frame-Options: DENY
310
```
311
Results in: `X-Frame-Options: DENY`
312

313
### add Action  
314
Adds a header value without removing existing values (allows multiple values).
315

316
```
317
add Vary: Accept-Encoding
318
add Vary: Accept-Language
319
```
320
Results in: 
321
```
322
Vary: Accept-Encoding
323
Vary: Accept-Language
324
```
325

326
### setDate Action
327
Sets a header with date formatting. Supports various date formats.
328

329
```
330
setDate Last-Modified: 2024-01-01T00:00:00Z
331
setDate Expires: +3600  (current time + 3600 seconds)
332
```
333

334
### addDate Action
335
Adds a date header without removing existing date headers.
336

337
```
338
addDate X-Generated: now
339
addDate X-Cache-Date: +86400
340
```
341

342
## Path Spec Patterns
343

344
HeaderFilter inherits path matching from IncludeExcludeBasedFilter:
345

346
- **Exact match**: `/admin/users` - matches exactly
347
- **Prefix match**: `/api/*` - matches all paths starting with `/api/`
348
- **Suffix match**: `*.css` - matches all paths ending with `.css`
349
- **Regex match**: `^/user/\d+$` - matches paths with regex pattern
350

351
## MIME Type Filtering
352

353
Filter headers based on response content type:
354

355
```xml
356
<init-param>
357
    <param-name>includedMimeTypes</param-name>
358
    <param-value>text/html,application/json</param-value>
359
</init-param>
360
<init-param>
361
    <param-name>excludedMimeTypes</param-name>
362
    <param-value>image/*,application/octet-stream</param-value>
363
</init-param>
364
```
365

366
## HTTP Method Filtering
367

368
Apply headers only to specific HTTP methods:
369

370
```xml
371
<init-param>
372
    <param-name>includedHttpMethods</param-name>
373
    <param-value>GET,POST</param-value>
374
</init-param>
375
<init-param>
376
    <param-name>excludedHttpMethods</param-name>
377
    <param-value>OPTIONS,HEAD</param-value>
378
</init-param>
379
```
380

381
## Common Use Cases
382

383
### Security Headers
384
- `X-Frame-Options` - Clickjacking protection
385
- `X-Content-Type-Options` - MIME type sniffing protection  
386
- `X-XSS-Protection` - XSS filter control
387
- `Content-Security-Policy` - Content security policy
388
- `Strict-Transport-Security` - HTTPS enforcement
389

390
### Cache Control
391
- `Cache-Control` - Browser and proxy caching directives
392
- `Expires` - Absolute expiration time
393
- `ETag` - Entity tag for conditional requests
394
- `Last-Modified` - Last modification timestamp
395

396
### API Headers
397
- `X-API-Version` - API version information
398
- `X-Rate-Limit-*` - Rate limiting information
399
- `X-Request-ID` - Request tracing identifier
400

401
### CORS Headers
402
- `Access-Control-Allow-Origin` - Allowed origins
403
- `Access-Control-Allow-Methods` - Allowed methods
404
- `Access-Control-Max-Age` - Preflight cache duration