001/*
002 * Copyright 2002-2017 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.web.reactive.socket;
018
019import org.springframework.lang.Nullable;
020import org.springframework.util.Assert;
021import org.springframework.util.ObjectUtils;
022
023/**
024 * Representation of WebSocket "close" status codes and reasons. Status codes
025 * in the 1xxx range are pre-defined by the protocol.
026 *
027 * @author Rossen Stoyanchev
028 * @since 5.0
029 * @see <a href="https://tools.ietf.org/html/rfc6455#section-7.4.1">
030 *     RFC 6455, Section 7.4.1 "Defined Status Codes"</a>
031 */
032public final class CloseStatus {
033
034        /**
035         * "1000 indicates a normal closure, meaning that the purpose for which the connection
036         * was established has been fulfilled."
037         */
038        public static final CloseStatus NORMAL = new CloseStatus(1000);
039
040        /**
041         * "1001 indicates that an endpoint is "going away", such as a server going down or a
042         * browser having navigated away from a page."
043         */
044        public static final CloseStatus GOING_AWAY = new CloseStatus(1001);
045
046        /**
047         * "1002 indicates that an endpoint is terminating the connection due to a protocol
048         * error."
049         */
050        public static final CloseStatus PROTOCOL_ERROR  = new CloseStatus(1002);
051
052        /**
053         * "1003 indicates that an endpoint is terminating the connection because it has
054         * received a type of data it cannot accept (e.g., an endpoint that understands only
055         * text data MAY send this if it receives a binary message)."
056         */
057        public static final CloseStatus NOT_ACCEPTABLE = new CloseStatus(1003);
058
059        // 10004: Reserved.
060        // The specific meaning might be defined in the future.
061
062        /**
063         * "1005 is a reserved value and MUST NOT be set as a status code in a Close control
064         * frame by an endpoint. It is designated for use in applications expecting a status
065         * code to indicate that no status code was actually present."
066         */
067        public static final CloseStatus NO_STATUS_CODE = new CloseStatus(1005);
068
069        /**
070         * "1006 is a reserved value and MUST NOT be set as a status code in a Close control
071         * frame by an endpoint. It is designated for use in applications expecting a status
072         * code to indicate that the connection was closed abnormally, e.g., without sending
073         * or receiving a Close control frame."
074         */
075        public static final CloseStatus NO_CLOSE_FRAME = new CloseStatus(1006);
076
077        /**
078         * "1007 indicates that an endpoint is terminating the connection because it has
079         * received data within a message that was not consistent with the type of the message
080         * (e.g., non-UTF-8 [RFC3629] data within a text message)."
081         */
082        public static final CloseStatus BAD_DATA = new CloseStatus(1007);
083
084        /**
085         * "1008 indicates that an endpoint is terminating the connection because it has
086         * received a message that violates its policy. This is a generic status code that can
087         * be returned when there is no other more suitable status code (e.g., 1003 or 1009)
088         * or if there is a need to hide specific details about the policy."
089         */
090        public static final CloseStatus POLICY_VIOLATION = new CloseStatus(1008);
091
092        /**
093         * "1009 indicates that an endpoint is terminating the connection because it has
094         * received a message that is too big for it to process."
095         */
096        public static final CloseStatus TOO_BIG_TO_PROCESS = new CloseStatus(1009);
097
098        /**
099         * "1010 indicates that an endpoint (client) is terminating the connection because it
100         * has expected the server to negotiate one or more extension, but the server didn't
101         * return them in the response message of the WebSocket handshake. The list of
102         * extensions that are needed SHOULD appear in the /reason/ part of the Close frame.
103         * Note that this status code is not used by the server, because it can fail the
104         * WebSocket handshake instead."
105         */
106        public static final CloseStatus REQUIRED_EXTENSION = new CloseStatus(1010);
107
108        /**
109         * "1011 indicates that a server is terminating the connection because it encountered
110         * an unexpected condition that prevented it from fulfilling the request."
111         */
112        public static final CloseStatus SERVER_ERROR = new CloseStatus(1011);
113
114        /**
115         * "1012 indicates that the service is restarted. A client may reconnect, and if it
116         * chooses to do, should reconnect using a randomized delay of 5 - 30s."
117         */
118        public static final CloseStatus SERVICE_RESTARTED = new CloseStatus(1012);
119
120        /**
121         * "1013 indicates that the service is experiencing overload. A client should only
122         * connect to a different IP (when there are multiple for the target) or reconnect to
123         * the same IP upon user action."
124         */
125        public static final CloseStatus SERVICE_OVERLOAD = new CloseStatus(1013);
126
127        /**
128         * "1015 is a reserved value and MUST NOT be set as a status code in a Close control
129         * frame by an endpoint. It is designated for use in applications expecting a status
130         * code to indicate that the connection was closed due to a failure to perform a TLS
131         * handshake (e.g., the server certificate can't be verified)."
132         */
133        public static final CloseStatus TLS_HANDSHAKE_FAILURE = new CloseStatus(1015);
134
135
136        private final int code;
137
138        @Nullable
139        private final String reason;
140
141
142        /**
143         * Create a new {@link CloseStatus} instance.
144         * @param code the status code
145         */
146        public CloseStatus(int code) {
147                this(code, null);
148        }
149
150        /**
151         * Create a new {@link CloseStatus} instance.
152         * @param code the status code
153         * @param reason the reason
154         */
155        public CloseStatus(int code, @Nullable String reason) {
156                Assert.isTrue((code >= 1000 && code < 5000), "Invalid status code");
157                this.code = code;
158                this.reason = reason;
159        }
160
161
162        /**
163         * Return the status code.
164         */
165        public int getCode() {
166                return this.code;
167        }
168
169        /**
170         * Return the reason, or {@code null} if none.
171         */
172        @Nullable
173        public String getReason() {
174                return this.reason;
175        }
176
177        /**
178         * Create a new {@link CloseStatus} from this one with the specified reason.
179         * @param reason the reason
180         * @return a new {@link CloseStatus} instance
181         */
182        public CloseStatus withReason(String reason) {
183                Assert.hasText(reason, "Reason must not be empty");
184                return new CloseStatus(this.code, reason);
185        }
186
187
188        public boolean equalsCode(CloseStatus other) {
189                return (this.code == other.code);
190        }
191
192        @Override
193        public boolean equals(@Nullable Object other) {
194                if (this == other) {
195                        return true;
196                }
197                if (!(other instanceof CloseStatus)) {
198                        return false;
199                }
200                CloseStatus otherStatus = (CloseStatus) other;
201                return (this.code == otherStatus.code &&
202                                ObjectUtils.nullSafeEquals(this.reason, otherStatus.reason));
203        }
204
205        @Override
206        public int hashCode() {
207                return this.code * 29 + ObjectUtils.nullSafeHashCode(this.reason);
208        }
209
210        @Override
211        public String toString() {
212                return "CloseStatus[code=" + this.code + ", reason=" + this.reason + "]";
213        }
214
215}