1- // Package errors provides internal-facing error types for use in Boulder. Many
2- // of these are transformed directly into Problem Details documents by the WFE.
3- // Some, like NotFound, may be handled internally. We avoid using Problem
4- // Details documents as part of our internal error system to avoid layering
5- // confusions.
1+ // Package errors provide a special error type for use in Boulder. This error
2+ // type carries additional type information with it, and has two special powers:
63//
7- // These errors are specifically for use in errors that cross RPC boundaries.
8- // An error type that does not need to be passed through an RPC can use a plain
9- // Go type locally. Our gRPC code is aware of these error types and will
10- // serialize and deserialize them automatically.
4+ // 1. It is recognized by our gRPC code, and the type metadata and detail string
5+ // will cross gRPC boundaries intact.
6+ //
7+ // 2. It is recognized by our frontend API "rendering" code, and will be
8+ // automatically converted to the corresponding urn:ietf:params:acme:error:...
9+ // ACME Problem Document.
10+ //
11+ // This means that a deeply-nested service (such as the SA) that wants to ensure
12+ // that the ACME client sees a particular problem document (such as NotFound)
13+ // can return a BoulderError and be sure that it will be propagated all the way
14+ // to the client.
15+ //
16+ // Note, however, that any additional context wrapped *around* the BoulderError
17+ // (such as by fmt.Errorf("oops: %w")) will be lost when the error is converted
18+ // into a problem document. Similarly, any type information wrapped *by* a
19+ // BoulderError (such as a sql.ErrNoRows) is lost at the gRPC serialization
20+ // boundary.
1121package errors
1222
1323import (
@@ -85,10 +95,15 @@ type SubBoulderError struct {
8595 Identifier identifier.ACMEIdentifier
8696}
8797
98+ // Error implements the error interface, returning a string representation of
99+ // this error.
88100func (be * BoulderError ) Error () string {
89101 return be .Detail
90102}
91103
104+ // Unwrap implements the optional error-unwrapping interface. It returns the
105+ // underlying type, all of when themselves implement the error interface, so
106+ // that `if errors.Is(someError, berrors.Malformed)` works.
92107func (be * BoulderError ) Unwrap () error {
93108 return be .Type
94109}
@@ -164,134 +179,134 @@ func New(errType ErrorType, msg string) error {
164179
165180// newf is a convenience function for creating a new BoulderError with a
166181// formatted message.
167- func newf (errType ErrorType , msg string , args ... interface {} ) error {
182+ func newf (errType ErrorType , msg string , args ... any ) error {
168183 return & BoulderError {
169184 Type : errType ,
170185 Detail : fmt .Sprintf (msg , args ... ),
171186 }
172187}
173188
174- func InternalServerError (msg string , args ... interface {} ) error {
189+ func InternalServerError (msg string , args ... any ) error {
175190 return newf (InternalServer , msg , args ... )
176191}
177192
178- func MalformedError (msg string , args ... interface {} ) error {
193+ func MalformedError (msg string , args ... any ) error {
179194 return newf (Malformed , msg , args ... )
180195}
181196
182- func UnauthorizedError (msg string , args ... interface {} ) error {
197+ func UnauthorizedError (msg string , args ... any ) error {
183198 return newf (Unauthorized , msg , args ... )
184199}
185200
186- func NotFoundError (msg string , args ... interface {} ) error {
201+ func NotFoundError (msg string , args ... any ) error {
187202 return newf (NotFound , msg , args ... )
188203}
189204
190- func RateLimitError (retryAfter time.Duration , msg string , args ... interface {} ) error {
205+ func RateLimitError (retryAfter time.Duration , msg string , args ... any ) error {
191206 return & BoulderError {
192207 Type : RateLimit ,
193208 Detail : fmt .Sprintf (msg + ": see https://letsencrypt.org/docs/rate-limits/" , args ... ),
194209 RetryAfter : retryAfter ,
195210 }
196211}
197212
198- func RegistrationsPerIPAddressError (retryAfter time.Duration , msg string , args ... interface {} ) error {
213+ func RegistrationsPerIPAddressError (retryAfter time.Duration , msg string , args ... any ) error {
199214 return & BoulderError {
200215 Type : RateLimit ,
201216 Detail : fmt .Sprintf (msg + ": see https://letsencrypt.org/docs/rate-limits/#new-registrations-per-ip-address" , args ... ),
202217 RetryAfter : retryAfter ,
203218 }
204219}
205220
206- func RegistrationsPerIPv6RangeError (retryAfter time.Duration , msg string , args ... interface {} ) error {
221+ func RegistrationsPerIPv6RangeError (retryAfter time.Duration , msg string , args ... any ) error {
207222 return & BoulderError {
208223 Type : RateLimit ,
209224 Detail : fmt .Sprintf (msg + ": see https://letsencrypt.org/docs/rate-limits/#new-registrations-per-ipv6-range" , args ... ),
210225 RetryAfter : retryAfter ,
211226 }
212227}
213228
214- func NewOrdersPerAccountError (retryAfter time.Duration , msg string , args ... interface {} ) error {
229+ func NewOrdersPerAccountError (retryAfter time.Duration , msg string , args ... any ) error {
215230 return & BoulderError {
216231 Type : RateLimit ,
217232 Detail : fmt .Sprintf (msg + ": see https://letsencrypt.org/docs/rate-limits/#new-orders-per-account" , args ... ),
218233 RetryAfter : retryAfter ,
219234 }
220235}
221236
222- func CertificatesPerDomainError (retryAfter time.Duration , msg string , args ... interface {} ) error {
237+ func CertificatesPerDomainError (retryAfter time.Duration , msg string , args ... any ) error {
223238 return & BoulderError {
224239 Type : RateLimit ,
225240 Detail : fmt .Sprintf (msg + ": see https://letsencrypt.org/docs/rate-limits/#new-certificates-per-registered-domain" , args ... ),
226241 RetryAfter : retryAfter ,
227242 }
228243}
229244
230- func CertificatesPerFQDNSetError (retryAfter time.Duration , msg string , args ... interface {} ) error {
245+ func CertificatesPerFQDNSetError (retryAfter time.Duration , msg string , args ... any ) error {
231246 return & BoulderError {
232247 Type : RateLimit ,
233248 Detail : fmt .Sprintf (msg + ": see https://letsencrypt.org/docs/rate-limits/#new-certificates-per-exact-set-of-hostnames" , args ... ),
234249 RetryAfter : retryAfter ,
235250 }
236251}
237252
238- func FailedAuthorizationsPerDomainPerAccountError (retryAfter time.Duration , msg string , args ... interface {} ) error {
253+ func FailedAuthorizationsPerDomainPerAccountError (retryAfter time.Duration , msg string , args ... any ) error {
239254 return & BoulderError {
240255 Type : RateLimit ,
241256 Detail : fmt .Sprintf (msg + ": see https://letsencrypt.org/docs/rate-limits/#authorization-failures-per-hostname-per-account" , args ... ),
242257 RetryAfter : retryAfter ,
243258 }
244259}
245260
246- func RejectedIdentifierError (msg string , args ... interface {} ) error {
261+ func RejectedIdentifierError (msg string , args ... any ) error {
247262 return newf (RejectedIdentifier , msg , args ... )
248263}
249264
250- func InvalidEmailError (msg string , args ... interface {} ) error {
265+ func InvalidEmailError (msg string , args ... any ) error {
251266 return newf (InvalidEmail , msg , args ... )
252267}
253268
254- func UnsupportedContactError (msg string , args ... interface {} ) error {
269+ func UnsupportedContactError (msg string , args ... any ) error {
255270 return newf (UnsupportedContact , msg , args ... )
256271}
257272
258- func ConnectionFailureError (msg string , args ... interface {} ) error {
273+ func ConnectionFailureError (msg string , args ... any ) error {
259274 return newf (ConnectionFailure , msg , args ... )
260275}
261276
262- func CAAError (msg string , args ... interface {} ) error {
277+ func CAAError (msg string , args ... any ) error {
263278 return newf (CAA , msg , args ... )
264279}
265280
266- func MissingSCTsError (msg string , args ... interface {} ) error {
281+ func MissingSCTsError (msg string , args ... any ) error {
267282 return newf (MissingSCTs , msg , args ... )
268283}
269284
270- func DuplicateError (msg string , args ... interface {} ) error {
285+ func DuplicateError (msg string , args ... any ) error {
271286 return newf (Duplicate , msg , args ... )
272287}
273288
274- func OrderNotReadyError (msg string , args ... interface {} ) error {
289+ func OrderNotReadyError (msg string , args ... any ) error {
275290 return newf (OrderNotReady , msg , args ... )
276291}
277292
278- func DNSError (msg string , args ... interface {} ) error {
293+ func DNSError (msg string , args ... any ) error {
279294 return newf (DNS , msg , args ... )
280295}
281296
282- func BadPublicKeyError (msg string , args ... interface {} ) error {
297+ func BadPublicKeyError (msg string , args ... any ) error {
283298 return newf (BadPublicKey , msg , args ... )
284299}
285300
286- func BadCSRError (msg string , args ... interface {} ) error {
301+ func BadCSRError (msg string , args ... any ) error {
287302 return newf (BadCSR , msg , args ... )
288303}
289304
290- func AlreadyReplacedError (msg string , args ... interface {} ) error {
305+ func AlreadyReplacedError (msg string , args ... any ) error {
291306 return newf (AlreadyReplaced , msg , args ... )
292307}
293308
294- func AlreadyRevokedError (msg string , args ... interface {} ) error {
309+ func AlreadyRevokedError (msg string , args ... any ) error {
295310 return newf (AlreadyRevoked , msg , args ... )
296311}
297312
@@ -303,18 +318,18 @@ func UnknownSerialError() error {
303318 return newf (UnknownSerial , "unknown serial" )
304319}
305320
306- func InvalidProfileError (msg string , args ... interface {} ) error {
321+ func InvalidProfileError (msg string , args ... any ) error {
307322 return newf (InvalidProfile , msg , args ... )
308323}
309324
310- func BadSignatureAlgorithmError (msg string , args ... interface {} ) error {
325+ func BadSignatureAlgorithmError (msg string , args ... any ) error {
311326 return newf (BadSignatureAlgorithm , msg , args ... )
312327}
313328
314- func AccountDoesNotExistError (msg string , args ... interface {} ) error {
329+ func AccountDoesNotExistError (msg string , args ... any ) error {
315330 return newf (AccountDoesNotExist , msg , args ... )
316331}
317332
318- func BadNonceError (msg string , args ... interface {} ) error {
333+ func BadNonceError (msg string , args ... any ) error {
319334 return newf (BadNonce , msg , args ... )
320335}
0 commit comments