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