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 }