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

1 module hunt.http.codec.websocket.model.UpgradeResponse;
2 
3 import hunt.http.codec.websocket.model.ExtensionConfig;
4 
5 import hunt.collection;
6 import hunt.Exceptions;
7 
8 /**
9  * The HTTP Upgrade to WebSocket Response
10  */
11 interface UpgradeResponse {
12     /**
13      * Add a header value to the response.
14      *
15      * @param name  the header name
16      * @param value the header value
17      */
18     void addHeader(string name, string value);
19 
20     /**
21      * Get the accepted WebSocket protocol.
22      *
23      * @return the accepted WebSocket protocol.
24      */
25     string getAcceptedSubProtocol();
26 
27     /**
28      * Get the list of extensions that should be used for the websocket.
29      *
30      * @return the list of negotiated extensions to use.
31      */
32     List!(ExtensionConfig) getExtensions();
33 
34     /**
35      * Get a header value
36      *
37      * @param name the header name
38      * @return the value (null if header doesn't exist)
39      */
40     string getHeader(string name);
41 
42     /**
43      * Get the header names
44      *
45      * @return the set of header names
46      */
47     Set!(string) getHeaderNames();
48 
49     /**
50      * Get the headers map
51      *
52      * @return the map of headers
53      */
54     Map!(string, List!(string)) getHeaders();
55 
56     /**
57      * Get the multi-value header value
58      *
59      * @param name the header name
60      * @return the list of values (null if header doesn't exist)
61      */
62     List!(string) getHeaders(string name);
63 
64     /**
65      * Get the HTTP Response Status Code
66      *
67      * @return the status code
68      */
69     int getStatusCode();
70 
71     /**
72      * Get the HTTP Response Status Reason
73      *
74      * @return the HTTP Response status reason
75      */
76     string getStatusReason();
77 
78     /**
79      * Test if upgrade response is successful.
80      * !(p)
81      * Merely notes if the response was sent as a WebSocket Upgrade,
82      * or was failed (resulting in no upgrade handshake)
83      *
84      * @return true if upgrade response was generated, false if no upgrade response was generated
85      */
86     bool isSuccess();
87 
88     /**
89      * Issue a forbidden upgrade response.
90      * !(p)
91      * This means that the websocket endpoint was valid, but the conditions to use a WebSocket resulted in a forbidden
92      * access.
93      * !(p)
94      * Use this when the origin or authentication is invalid.
95      *
96      * @param message the short 1 line detail message about the forbidden response
97      * @throws IOException if unable to send the forbidden
98      */
99     void sendForbidden(string message);
100 
101     /**
102      * Set the accepted WebSocket Protocol.
103      *
104      * @param protocol the protocol to list as accepted
105      */
106     void setAcceptedSubProtocol(string protocol);
107 
108     /**
109      * Set the list of extensions that are approved for use with this websocket.
110      * !(p)
111      * Notes:
112      * !(ul)
113      * !(li)Per the spec you cannot add extensions that have not been seen in the {@link UpgradeRequest}, just remove
114      * entries you don't want to use!(/li)
115      * !(li)If this is unused, or a null is passed, then the list negotiation will follow default behavior and use the
116      * complete list of extensions that are
117      * available in this WebSocket server implementation.!(/li)
118      * !(/ul)
119      *
120      * @param extensions the list of extensions to use.
121      */
122     void setExtensions(List!(ExtensionConfig) extensions);
123 
124     /**
125      * Set a header
126      * !(p)
127      * Overrides previous value of header (if set)
128      *
129      * @param name  the header name
130      * @param value the header value
131      */
132     void setHeader(string name, string value);
133 
134     /**
135      * Set the HTTP Response status code
136      *
137      * @param statusCode the status code
138      */
139     void setStatusCode(int statusCode);
140 
141     /**
142      * Set the HTTP Response status reason phrase
143      * !(p)
144      * Note, not all implementation of UpgradeResponse can support this feature
145      *
146      * @param statusReason the status reason phrase
147      */
148     void setStatusReason(string statusReason);
149 
150     /**
151      * Set the success of the upgrade response.
152      * !(p)
153      *
154      * @param success true to indicate a response to the upgrade handshake was sent, false to indicate no upgrade
155      *                response was sent
156      */
157     void setSuccess(bool success);
158 }