1 package org.apache.maven.wagon.shared.http;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import org.apache.maven.wagon.ResourceDoesNotExistException;
23 import org.apache.maven.wagon.TransferFailedException;
24 import org.apache.maven.wagon.authorization.AuthorizationException;
25 import org.apache.maven.wagon.proxy.ProxyInfo;
26 import org.codehaus.plexus.util.StringUtils;
27
28 /**
29 * Helper for HTTP related messages.
30 * <p>
31 * <b>Important notice on Reason Phrase</b>:
32 * <ul>
33 * <li>reason phrase was <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html">defined by initial HTTP/1.1
34 * RFC 2616</a>: <cite>The Reason-Phrase is intended to give a short textual description of the Status-Code. The
35 * Status-Code is intended for use by automata and the Reason-Phrase is intended for the human user. The client is not
36 * required to examine or display the Reason- Phrase.</cite></li>
37 * <li>it has been later largely deprecated in <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">the updated
38 * HTTP/1.1 RFC-7230</a>: <cite>The reason-phrase element exists for the sole purpose of providing a textual description
39 * associated with the numeric status code, mostly out of deference to earlier Internet application protocols that were
40 * more frequently used with interactive text clients. A client SHOULD ignore the reason-phrase content.</cite></li>
41 * <li>it has been removed from <a href="https://tools.ietf.org/html/rfc7540#section-8.1.2.4">HTTP/2 RFC 7540</a>:
42 * <cite>HTTP/2 does not define a way to carry the version or reason phrase that is included in an HTTP/1.1 status
43 * line.</cite>.</li>
44 * </ul>
45 * The use of Reason Phrase done here to improve the message to the end-user (particularly in case of failures) will
46 * disappear while HTTP/2 is deployed: a new mechanism to provide such a message needs to be defined...
47 *
48 * @since 3.3.4
49 */
50 public class HttpMessageUtils
51 {
52 // status codes here to avoid checkstyle magic number and not have have hard depend on non-wagon classes
53 private static final int SC_UNAUTHORIZED = 401;
54 private static final int SC_FORBIDDEN = 403;
55 private static final int SC_NOT_FOUND = 404;
56 private static final int SC_PROXY_AUTH_REQUIRED = 407;
57 private static final int SC_GONE = 410;
58
59 /**
60 * A HTTP status code used to indicate that the actual response status code is not known at time of message
61 * generation.
62 */
63 public static final int UNKNOWN_STATUS_CODE = -1;
64
65 /**
66 * Format a consistent HTTP transfer debug message combining url, status code, status line reason phrase and HTTP
67 * proxy server info.
68 * <p>
69 * Url will always be included in the message. A status code other than {@link #UNKNOWN_STATUS_CODE} will be
70 * included. A reason phrase will only be included if non-empty and status code is not {@link #UNKNOWN_STATUS_CODE}.
71 * Proxy information will only be included if not null.
72 *
73 * @param url the required non-null URL associated with the message
74 * @param statusCode an HTTP response status code
75 * @param reasonPhrase an HTTP status line reason phrase
76 * @param proxyInfo proxy server used during the transfer, may be null if none used
77 * @return a formatted debug message combining the parameters of this method
78 * @throws NullPointerException if url is null
79 */
80 public static String formatTransferDebugMessage( String url, int statusCode, String reasonPhrase,
81 ProxyInfo proxyInfo )
82 {
83 String msg = url;
84 if ( statusCode != UNKNOWN_STATUS_CODE )
85 {
86 msg += " -- status code: " + statusCode;
87 if ( StringUtils.isNotEmpty( reasonPhrase ) )
88 {
89 msg += ", reason phrase: " + reasonPhrase;
90 }
91 }
92 if ( proxyInfo != null )
93 {
94 msg += " -- " + proxyInfo.toString();
95 }
96 return msg;
97 }
98
99 /**
100 * Format a consistent message for HTTP related {@link TransferFailedException}.
101 * <p>
102 * This variation typically used in cases where there is no HTTP transfer response data to extract status code and
103 * reason phrase from. Equivalent to calling {@link #formatTransferFailedMessage(String, int, String, ProxyInfo)}
104 * with {@link #UNKNOWN_STATUS_CODE} and null reason phrase.
105 *
106 * @param url the URL associated with the message
107 * @param proxyInfo proxy server used during the transfer, may be null if none used
108 * @return a formatted failure message combining the parameters of this method
109 */
110 public static String formatTransferFailedMessage( String url, ProxyInfo proxyInfo )
111 {
112 return formatTransferFailedMessage( url, UNKNOWN_STATUS_CODE, null,
113 proxyInfo );
114 }
115
116 /**
117 * Format a consistent message for HTTP related {@link TransferFailedException}.
118 *
119 * @param url the URL associated with the message
120 * @param statusCode an HTTP response status code or {@link #UNKNOWN_STATUS_CODE}
121 * @param reasonPhrase an HTTP status line reason phrase or null if the reason phrase unknown
122 * @param proxyInfo proxy server used during the transfer, may be null if none used
123 * @return a formatted failure message combining the parameters of this method
124 */
125 public static String formatTransferFailedMessage( String url, int statusCode, String reasonPhrase,
126 ProxyInfo proxyInfo )
127 {
128 return formatMessage( "Transfer failed for ", url, statusCode, reasonPhrase, proxyInfo );
129 }
130
131 /**
132 * Format a consistent message for HTTP related {@link AuthorizationException}.
133 * <p>
134 * The message will always include the URL and status code provided. If empty, the reason phrase is substituted with
135 * a common reason based on status code. {@link ProxyInfo} is only included in the message if not null.
136 *
137 * @param url the URL associated with the message
138 * @param statusCode an HTTP response status code related to auth
139 * @param reasonPhrase an HTTP status line reason phrase
140 * @param proxyInfo proxy server used during the transfer, may be null if none used
141 * @return a consistent message for a HTTP related {@link AuthorizationException}
142 */
143 public static String formatAuthorizationMessage( String url, int statusCode, String reasonPhrase,
144 ProxyInfo proxyInfo )
145 {
146 switch ( statusCode )
147 {
148 case SC_UNAUTHORIZED: // no credentials or auth was not valid
149 return formatMessage( "Authentication failed for ", url, statusCode, reasonPhrase, null );
150
151 case SC_FORBIDDEN: // forbidden based on permissions usually
152 return formatMessage( "Authorization failed for ", url, statusCode, reasonPhrase, null );
153
154 case SC_PROXY_AUTH_REQUIRED:
155 return formatMessage( "HTTP proxy server authentication failed for ", url, statusCode,
156 reasonPhrase, null );
157
158 default:
159 break;
160 }
161
162 return formatMessage( "Authorization failed for ", url, statusCode, reasonPhrase, proxyInfo );
163 }
164
165 /**
166 * Format a consistent message for HTTP related {@link ResourceDoesNotExistException}.
167 * <p>
168 * The message will always include the URL and status code provided. If empty, the reason phrase is substituted with
169 * the commonly used reason phrases per status code. {@link ProxyInfo} is only included if not null.
170 *
171 * @param url the URL associated with the message
172 * @param statusCode an HTTP response status code related to resources not being found
173 * @param reasonPhrase an HTTP status line reason phrase
174 * @param proxyInfo proxy server used during the transfer, may be null if none used
175 * @return a consistent message for a HTTP related {@link ResourceDoesNotExistException}
176 */
177 public static String formatResourceDoesNotExistMessage( String url, int statusCode, String reasonPhrase,
178 ProxyInfo proxyInfo )
179 {
180 return formatMessage( "Resource missing at ", url, statusCode, reasonPhrase, proxyInfo );
181 }
182
183 private static String formatMessage( String message, String url, int statusCode, String reasonPhrase,
184 ProxyInfo proxyInfo )
185 {
186 String msg = message + url;
187 if ( statusCode != UNKNOWN_STATUS_CODE )
188 {
189 msg += " " + statusCode;
190
191 if ( StringUtils.isNotEmpty( reasonPhrase ) )
192 {
193 msg += " " + reasonPhrase;
194 }
195 else
196 {
197 switch ( statusCode )
198 {
199 case SC_UNAUTHORIZED:
200 msg += " Unauthorized";
201 break;
202
203 case SC_FORBIDDEN:
204 msg += " Forbidden";
205 break;
206
207 case SC_NOT_FOUND:
208 msg += " Not Found";
209 break;
210
211 case SC_PROXY_AUTH_REQUIRED:
212 msg += " Proxy Authentication Required";
213 break;
214
215 case SC_GONE:
216 msg += " Gone";
217 break;
218
219 default:
220 break;
221 }
222 }
223 }
224 if ( proxyInfo != null )
225 {
226 msg += " " + proxyInfo.toString();
227 }
228 return msg;
229 }
230 }