hunt.http.codec.websocket.model.UpgradeRequest source code

1 module hunt.http.codec.websocket.model.UpgradeRequest;
2 
3 import hunt.http.codec.websocket.model.ExtensionConfig;
4 import hunt.http.Cookie;
5 import hunt.net.util.HttpURI;
6 
7 // dfmt off
8 version(WITH_HUNT_SECURITY) {
9     // import hunt.security.Principal;
10 }
11 // dfmt on
12 
13 import hunt.collection;
14 
15 /**
16  * The HTTP Upgrade to WebSocket Request
17  */
18 interface UpgradeRequest {
19     /**
20      * Add WebSocket Extension Configuration(s) to Upgrade Request.
21      * <p>
22      * This is merely the list of requested Extensions to use, see {@link UpgradeResponse#getExtensions()} for what was
23      * negotiated
24      *
25      * @param configs the configuration(s) to add
26      */
27     void addExtensions(ExtensionConfig[] configs ...);
28 
29     /**
30      * Add WebSocket Extension Configuration(s) to request
31      * <p>
32      * This is merely the list of requested Extensions to use, see {@link UpgradeResponse#getExtensions()} for what was
33      * negotiated
34      *
35      * @param configs the configuration(s) to add
36      */
37     void addExtensions(string[] configs...);
38 
39     /**
40      * Get the list of Cookies on the Upgrade request
41      *
42      * @return the list of Cookies
43      */
44     List!(Cookie) getCookies();
45 
46     /**
47      * Get the list of WebSocket Extension Configurations for this Upgrade Request.
48      * <p>
49      * This is merely the list of requested Extensions to use, see {@link UpgradeResponse#getExtensions()} for what was
50      * negotiated
51      *
52      * @return the list of Extension configurations (in the order they were specified)
53      */
54     List!(ExtensionConfig) getExtensions();
55 
56     /**
57      * Get a specific Header value from Upgrade Request
58      *
59      * @param name the name of the header
60      * @return the value of the header (null if header does not exist)
61      */
62     string getHeader(string name);
63 
64     /**
65      * Get the specific Header value, as an <code>int</code>, from the Upgrade Request.
66      *
67      * @param name the name of the header
68      * @return the value of the header as an <code>int</code> (-1 if header does not exist)
69      * @throws NumberFormatException if unable to parse value as an int.
70      */
71     int getHeaderInt(string name);
72 
73     /**
74      * Get the headers as a Map of keys to value lists.
75      *
76      * @return the headers
77      */
78     Map!(string, List!(string)) getHeaders();
79 
80     /**
81      * Get the specific header values (for multi-value headers)
82      *
83      * @param name the header name
84      * @return the value list (null if no header exists)
85      */
86     List!(string) getHeaders(string name);
87 
88     /**
89      * The host of the Upgrade Request URI
90      *
91      * @return host of the request URI
92      */
93     string getHost();
94 
95     /**
96      * The HTTP version used for this Upgrade Request
97      * <p>
98      * As of <a href="http://tools.ietf.org/html/rfc6455">RFC6455 (December 2011)</a> this is always
99      * <code>HTTP/1.1</code>
100      *
101      * @return the HTTP Version used
102      */
103     string getHttpVersion();
104 
105     /**
106      * The HTTP method for this Upgrade Request.
107      * <p>
108      * As of <a href="http://tools.ietf.org/html/rfc6455">RFC6455 (December 2011)</a> this is always <code>GET</code>
109      *
110      * @return the HTTP method used
111      */
112     string getMethod();
113 
114     /**
115      * The WebSocket Origin of this Upgrade Request
116      * <p>
117      * See <a href="http://tools.ietf.org/html/rfc6455#section-10.2">RFC6455: Section 10.2</a> for details.
118      * <p>
119      * Equivalent to {@link #getHeader(string)} passed the "Origin" header.
120      *
121      * @return the Origin header
122      */
123     string getOrigin();
124 
125     /**
126      * Returns a map of the query parameters of the request.
127      *
128      * @return a unmodifiable map of query parameters of the request.
129      */
130     Map!(string, List!(string)) getParameterMap();
131 
132     /**
133      * Get the WebSocket Protocol Version
134      * <p>
135      * As of <a href="http://tools.ietf.org/html/rfc6455#section-11.6">RFC6455</a>, Hunt only supports version
136      * <code>13</code>
137      *
138      * @return the WebSocket protocol version
139      */
140     string getProtocolVersion();
141 
142     /**
143      * Get the Query string of the request URI.
144      *
145      * @return the request uri query string
146      */
147     string getQueryString();
148 
149     /**
150      * Get the Request URI
151      *
152      * @return the request URI
153      */
154     HttpURI getRequestURI();
155 
156     /**
157      * Access the Servlet HTTP Session (if present)
158      * <p>
159      * Note: Never present on a Client UpgradeRequest.
160      *
161      * @return the Servlet HttpSession on server side UpgradeRequests
162      */
163     Object getSession();
164 
165     /**
166      * Get the list of offered WebSocket sub-protocols.
167      *
168      * @return the list of offered sub-protocols
169      */
170     List!(string) getSubProtocols();
171 
172     /**
173      * Get the User Principal for this request.
174      * <p>
175      * Only applicable when using UpgradeRequest from server side.
176      *
177      * @return the user principal
178      */
179     // version(WITH_HUNT_SECURITY) Principal getUserPrincipal();
180 
181     /**
182      * Test if a specific sub-protocol is offered
183      *
184      * @param test the sub-protocol to test for
185      * @return true if sub-protocol exists on request
186      */
187     bool hasSubProtocol(string test);
188 
189     /**
190      * Test if supplied Origin is the same as the Request
191      *
192      * @param test the supplied origin
193      * @return true if the supplied origin matches the request origin
194      */
195     bool isOrigin(string test);
196 
197     /**
198      * Test if connection is secure.
199      *
200      * @return true if connection is secure.
201      */
202     bool isSecure();
203 
204     /**
205      * Set the list of Cookies on the request
206      *
207      * @param cookies the cookies to use
208      */
209     void setCookies(List!(Cookie) cookies);
210 
211     /**
212      * Set the list of WebSocket Extension configurations on the request.
213      *
214      * @param configs the list of extension configurations
215      */
216     void setExtensions(List!(ExtensionConfig) configs);
217 
218     /**
219      * Set a specific header with multi-value field
220      * <p>
221      * Overrides any previous value for this named header
222      *
223      * @param name   the name of the header
224      * @param values the multi-value field
225      */
226     void setHeader(string name, List!(string) values);
227 
228     /**
229      * Set a specific header value
230      * <p>
231      * Overrides any previous value for this named header
232      *
233      * @param name  the header to set
234      * @param value the value to set it to
235      */
236     void setHeader(string name, string value);
237 
238     /**
239      * Sets multiple headers on the request.
240      * <p>
241      * Only sets those headers provided, does not remove
242      * headers that exist on request and are not provided in the
243      * parameter for this method.
244      * <p>
245      * Convenience method vs calling {@link #setHeader(string, List)} multiple times.
246      *
247      * @param headers the headers to set
248      */
249     void setHeaders(Map!(string, List!(string)) headers);
250 
251     /**
252      * Set the HTTP Version to use.
253      * <p>
254      * As of <a href="http://tools.ietf.org/html/rfc6455">RFC6455 (December 2011)</a> this should always be
255      * <code>HTTP/1.1</code>
256      *
257      * @param httpVersion the HTTP version to use.
258      */
259     void setHttpVersion(string httpVersion);
260 
261     /**
262      * Set the HTTP method to use.
263      * <p>
264      * As of <a href="http://tools.ietf.org/html/rfc6455">RFC6455 (December 2011)</a> this is always <code>GET</code>
265      *
266      * @param method the HTTP method to use.
267      */
268     void setMethod(string method);
269 
270     /**
271      * Set the Request URI to use for this request.
272      * <p>
273      * Must be an absolute URI with scheme <code>'ws'</code> or <code>'wss'</code>
274      *
275      * @param uri the Request URI
276      */
277     void setRequestURI(HttpURI uri);
278 
279     /**
280      * Set the Session associated with this request.
281      * <p>
282      * Typically used to associate the Servlet HttpSession object.
283      *
284      * @param session the session object to associate with this request
285      */
286     void setSession(Object session);
287 
288     /**
289      * Set the offered WebSocket Sub-Protocol list.
290      *
291      * @param protocols the offered sub-protocol list
292      */
293     void setSubProtocols(List!(string) protocols);
294 
295     /**
296      * Set the offered WebSocket Sub-Protocol list.
297      *
298      * @param protocols the offered sub-protocol list
299      */
300     void setSubProtocols(string[] protocols...);
301 
302 }