Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 1 | /* |
| 2 | * Portions copyright 2019-present Open Networking Foundation |
| 3 | * Original copyright 2019-present Ciena Corporation |
| 4 | * |
| 5 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 6 | * you may not use this file except in compliance with the License. |
| 7 | * You may obtain a copy of the License at |
| 8 | * |
| 9 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 10 | * |
| 11 | * Unless required by applicable law or agreed to in writing, software |
| 12 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 14 | * See the License for the specific language governing permissions and |
| 15 | * limitations under the License. |
| 16 | */ |
| 17 | |
| 18 | package error |
| 19 | |
| 20 | /* Cordctl error classes |
| 21 | |
| 22 | The basic idea is to throw specific error classes, so it's easier to test for them rather than doing string |
| 23 | comparisons or other ad hoc mechanisms for determining the type of error. This decouples the human |
| 24 | readable text of an error from programmatic testing of error type. |
| 25 | |
| 26 | We differentiate between errors that we want to generate brief output, such as for example a |
| 27 | user mistyping a model name, versus errors that we want to generate additional context. This prevents |
| 28 | overwhelming a user with voluminous output for a simple mistake. A command-line option may be provided |
| 29 | to force full error output should it be desired. |
| 30 | |
| 31 | Additionally, an added benefit is ease of maintenance and localisation, by locating all error text |
| 32 | in one place. |
| 33 | |
| 34 | To return an error, for example: |
| 35 | |
| 36 | return WithStackTrace(&ChecksumMismatchError{Actual: "123", Expected: "456"}) |
| 37 | |
| 38 | To check to see if a specific error was returned, either of the following are acceptable: |
| 39 | |
| 40 | _, ok := err.(*ChecksumMismatchError) |
| 41 | ... |
| 42 | |
| 43 | switch err.(type) { |
| 44 | case *ChecksumMismatchError: |
| 45 | ... |
| 46 | */ |
| 47 | |
| 48 | import ( |
| 49 | "bytes" |
| 50 | "fmt" |
| 51 | go_errors "github.com/go-errors/errors" |
Scott Baker | ce11c49 | 2019-07-30 15:53:34 -0700 | [diff] [blame] | 52 | "github.com/opencord/cordctl/internal/pkg/config" |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 53 | "google.golang.org/grpc/status" |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 54 | "runtime" |
| 55 | "strings" |
| 56 | ) |
| 57 | |
| 58 | const ( |
| 59 | MaxStackDepth = 50 |
| 60 | ) |
| 61 | |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 62 | /* CordCtlError is the interface for errors created by cordctl. |
| 63 | * ShouldDumpStack() |
| 64 | * Returns false for well-understood problems such as invalid user input where a brief error message is sufficient |
| 65 | * Returns true for poorly-understood / unexpected problems where a full dump context may be useful |
| 66 | * Stack() |
| 67 | * Returns a string containing the stack trace where the error occurred |
| 68 | * Only useful if WithStackTrace() was called on the error |
| 69 | */ |
| 70 | |
| 71 | type CordCtlError interface { |
| 72 | error |
| 73 | ShouldDumpStack() bool |
| 74 | Stack() string |
| 75 | AddStackTrace(skip int) |
| 76 | } |
| 77 | |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 78 | /* ObjectReference contains information about the object that the error applies to. |
| 79 | This may be empty (ModelName="") or it may contain a ModelName together with |
| 80 | option Id or Queries. |
| 81 | */ |
| 82 | |
| 83 | type ObjectReference struct { |
| 84 | ModelName string |
| 85 | Id int32 |
| 86 | Queries map[string]string |
| 87 | } |
| 88 | |
| 89 | // Returns true if the reference is populated |
| 90 | func (f *ObjectReference) IsValid() bool { |
| 91 | return (f.ModelName != "") |
| 92 | } |
| 93 | |
| 94 | func (f *ObjectReference) String() string { |
| 95 | if !f.IsValid() { |
| 96 | // The reference is empty |
| 97 | return "" |
| 98 | } |
| 99 | |
| 100 | if f.Queries != nil { |
| 101 | kv := make([]string, 0, len(f.Queries)) |
| 102 | for k, v := range f.Queries { |
| 103 | kv = append(kv, fmt.Sprintf("%s%s", k, v)) |
| 104 | } |
| 105 | return fmt.Sprintf("%s <%v>", f.ModelName, strings.Join(kv, ", ")) |
| 106 | } |
| 107 | |
| 108 | if f.Id > 0 { |
| 109 | return fmt.Sprintf("%s <id=%d>", f.ModelName, f.Id) |
| 110 | } |
| 111 | |
| 112 | return fmt.Sprintf("%s", f.ModelName) |
| 113 | } |
| 114 | |
| 115 | // Returns " on model ModelName [id]" if the reference is populated, or "" otherwise. |
| 116 | func (f *ObjectReference) Clause() string { |
| 117 | if !f.IsValid() { |
| 118 | // The reference is empty |
| 119 | return "" |
| 120 | } |
| 121 | |
| 122 | return fmt.Sprintf(" [on model %s]", f.String()) |
| 123 | } |
| 124 | |
| 125 | /* BaseError |
| 126 | * |
| 127 | * Supports attaching stack traces to errors |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 128 | * Borrowed the technique from github.com/go-errors. Decided against using go-errors directly since it requires |
| 129 | * wrapping our error classes. Instead, incorporated the stack trace directly into our error class. |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 130 | * |
| 131 | * Also supports encapsulating error messages, so that a CordError can encapsulate the error message from a |
| 132 | * function that was called. |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 133 | */ |
| 134 | |
| 135 | type BaseError struct { |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 136 | Obj ObjectReference |
| 137 | Encapsulated error // in case this error encapsulates an error from a lower level |
| 138 | stack []uintptr // for stack trace |
| 139 | frames []go_errors.StackFrame // for stack trace |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 140 | } |
| 141 | |
| 142 | func (f *BaseError) AddStackTrace(skip int) { |
| 143 | stack := make([]uintptr, MaxStackDepth) |
| 144 | length := runtime.Callers(2+skip, stack[:]) |
| 145 | f.stack = stack[:length] |
| 146 | } |
| 147 | |
| 148 | func (f *BaseError) Stack() string { |
| 149 | buf := bytes.Buffer{} |
| 150 | |
| 151 | for _, frame := range f.StackFrames() { |
| 152 | buf.WriteString(frame.String()) |
| 153 | } |
| 154 | |
| 155 | return string(buf.Bytes()) |
| 156 | } |
| 157 | |
| 158 | func (f *BaseError) StackFrames() []go_errors.StackFrame { |
| 159 | if f.frames == nil { |
| 160 | f.frames = make([]go_errors.StackFrame, len(f.stack)) |
| 161 | |
| 162 | for i, pc := range f.stack { |
| 163 | f.frames[i] = go_errors.NewStackFrame(pc) |
| 164 | } |
| 165 | } |
| 166 | |
| 167 | return f.frames |
| 168 | } |
| 169 | |
| 170 | // *************************************************************************** |
| 171 | // UserError is composed into Errors that are due to user input |
| 172 | |
| 173 | type UserError struct { |
| 174 | BaseError |
| 175 | } |
| 176 | |
| 177 | func (f UserError) ShouldDumpStack() bool { |
| 178 | return false |
| 179 | } |
| 180 | |
| 181 | // ************************************************************************** |
| 182 | // TransferError is composed into Errors that are due to failures in transfers |
| 183 | |
| 184 | type TransferError struct { |
| 185 | BaseError |
| 186 | } |
| 187 | |
| 188 | func (f TransferError) ShouldDumpStack() bool { |
| 189 | return false |
| 190 | } |
| 191 | |
| 192 | // *************************************************************************** |
| 193 | // UnexpectedError is things that we don't expect to happen. They should |
| 194 | // generate maximum error context, to provide useful information for developer |
| 195 | // diagnosis. |
| 196 | |
| 197 | type UnexpectedError struct { |
| 198 | BaseError |
| 199 | } |
| 200 | |
| 201 | func (f UnexpectedError) ShouldDumpStack() bool { |
| 202 | return true |
| 203 | } |
| 204 | |
| 205 | // *************************************************************************** |
| 206 | // Specific error classes follow |
| 207 | |
| 208 | // Checksum mismatch when downloading or uploading a file |
| 209 | type ChecksumMismatchError struct { |
| 210 | TransferError |
| 211 | Name string // (optional) Name of file |
| 212 | Expected string |
| 213 | Actual string |
| 214 | } |
| 215 | |
| 216 | func (f ChecksumMismatchError) Error() string { |
| 217 | if f.Name != "" { |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 218 | return fmt.Sprintf("%s: checksum mismatch (actual=%s, expected=%s)", f.Name, f.Expected, f.Actual) |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 219 | } else { |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 220 | return fmt.Sprintf("checksum mismatch (actual=%s, expected=%s)", f.Expected, f.Actual) |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 221 | } |
| 222 | } |
| 223 | |
| 224 | // User specified a model type that is not valid |
| 225 | type UnknownModelTypeError struct { |
| 226 | UserError |
| 227 | Name string // Name of model |
| 228 | } |
| 229 | |
| 230 | func (f UnknownModelTypeError) Error() string { |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 231 | return fmt.Sprintf("Model %s does not exist. Use `cordctl modeltype list` to get a list of available models", f.Name) |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 232 | } |
| 233 | |
| 234 | // User specified a model state that is not valid |
| 235 | type UnknownModelStateError struct { |
| 236 | UserError |
| 237 | Name string // Name of state |
| 238 | } |
| 239 | |
| 240 | func (f UnknownModelStateError) Error() string { |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 241 | return fmt.Sprintf("Model state %s does not exist", f.Name) |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 242 | } |
| 243 | |
| 244 | // Command requires a filter be specified |
| 245 | type FilterRequiredError struct { |
| 246 | UserError |
| 247 | } |
| 248 | |
| 249 | func (f FilterRequiredError) Error() string { |
| 250 | return "Filter required. Use either an ID, --filter, or --all to specify which models to operate on" |
| 251 | } |
| 252 | |
| 253 | // Command was aborted by the user |
| 254 | type AbortedError struct { |
| 255 | UserError |
| 256 | } |
| 257 | |
| 258 | func (f AbortedError) Error() string { |
| 259 | return "Aborted" |
| 260 | } |
| 261 | |
| 262 | // Command was aborted by the user |
| 263 | type NoMatchError struct { |
| 264 | UserError |
| 265 | } |
| 266 | |
| 267 | func (f NoMatchError) Error() string { |
| 268 | return "No Match" |
| 269 | } |
| 270 | |
| 271 | // User specified a field name that is not valid |
| 272 | type FieldDoesNotExistError struct { |
| 273 | UserError |
| 274 | ModelName string |
| 275 | FieldName string |
| 276 | } |
| 277 | |
| 278 | func (f FieldDoesNotExistError) Error() string { |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 279 | return fmt.Sprintf("Model %s does not have field %s", f.ModelName, f.FieldName) |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 280 | } |
| 281 | |
| 282 | // User specified a query string that is not properly formatted |
| 283 | type IllegalQueryError struct { |
| 284 | UserError |
| 285 | Query string |
| 286 | } |
| 287 | |
| 288 | func (f IllegalQueryError) Error() string { |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 289 | return fmt.Sprintf("Illegal query string %s", f.Query) |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 290 | } |
| 291 | |
| 292 | // We failed to type convert something that we thought should have converted |
| 293 | type TypeConversionError struct { |
| 294 | UnexpectedError |
| 295 | Source string |
| 296 | Destination string |
| 297 | } |
| 298 | |
| 299 | func (f TypeConversionError) Error() string { |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 300 | return fmt.Sprintf("Failed to type convert from %s to %s", f.Source, f.Destination) |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 301 | } |
| 302 | |
| 303 | // Version did not match a constraint |
| 304 | type VersionConstraintError struct { |
| 305 | UserError |
| 306 | Name string |
| 307 | Version string |
| 308 | Constraint string |
| 309 | } |
| 310 | |
| 311 | func (f VersionConstraintError) Error() string { |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 312 | return fmt.Sprintf("%s version %s did not match constraint '%s'", f.Name, f.Version, f.Constraint) |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 313 | } |
| 314 | |
| 315 | // A model was not found |
| 316 | type ModelNotFoundError struct { |
| 317 | UserError |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 318 | } |
| 319 | |
| 320 | func (f ModelNotFoundError) Error() string { |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 321 | return fmt.Sprintf("Not Found%s", f.Obj.Clause()) |
| 322 | } |
| 323 | |
| 324 | // Permission Denied |
| 325 | type PermissionDeniedError struct { |
| 326 | UserError |
| 327 | } |
| 328 | |
| 329 | func (f PermissionDeniedError) Error() string { |
| 330 | return fmt.Sprintf("Permission Denied%s. Please verify username and password are correct", f.Obj.Clause()) |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 331 | } |
| 332 | |
Scott Baker | ce11c49 | 2019-07-30 15:53:34 -0700 | [diff] [blame] | 333 | // Unavailable |
| 334 | type UnavailableError struct { |
| 335 | UserError |
| 336 | } |
| 337 | |
| 338 | func (f UnavailableError) Error() string { |
| 339 | return fmt.Sprintf("Server Unavailable%s. Please verify server settings (%s). If correct, this may be a transient failure -- please try again", f.Obj.Clause(), config.GlobalConfig.Server) |
| 340 | } |
| 341 | |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 342 | // InvalidInputError is a catch-all for user mistakes that aren't covered elsewhere |
| 343 | type InvalidInputError struct { |
| 344 | UserError |
| 345 | Message string |
| 346 | } |
| 347 | |
| 348 | func (f InvalidInputError) Error() string { |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 349 | return fmt.Sprintf("%s", f.Message) |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 350 | } |
| 351 | |
| 352 | func NewInvalidInputError(format string, params ...interface{}) *InvalidInputError { |
| 353 | msg := fmt.Sprintf(format, params...) |
| 354 | err := &InvalidInputError{Message: msg} |
| 355 | err.AddStackTrace(2) |
| 356 | return err |
| 357 | } |
| 358 | |
| 359 | // InternalError is a catch-all for errors that don't fit somewhere else |
| 360 | type InternalError struct { |
| 361 | UnexpectedError |
| 362 | Message string |
| 363 | } |
| 364 | |
| 365 | func (f InternalError) Error() string { |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 366 | return fmt.Sprintf("Internal Error%s: %s", f.Obj.Clause(), f.Message) |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 367 | } |
| 368 | |
| 369 | func NewInternalError(format string, params ...interface{}) *InternalError { |
| 370 | msg := fmt.Sprintf(format, params...) |
| 371 | err := &InternalError{Message: msg} |
| 372 | err.AddStackTrace(2) |
| 373 | return err |
| 374 | } |
| 375 | |
| 376 | // *************************************************************************** |
| 377 | // Global exported function declarations |
| 378 | |
| 379 | // Attach a stack trace to an error. The error passed in must be a pointer to an error structure for the |
| 380 | // CordCtlError interface to match. |
| 381 | func WithStackTrace(err CordCtlError) error { |
| 382 | err.AddStackTrace(2) |
| 383 | return err |
| 384 | } |
| 385 | |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 386 | /* RpcErrorWithObjToCordError |
| 387 | * |
| 388 | * Convert an RPC error into a Cord Error. The ObjectReference allows methods to attach |
| 389 | * object-related information to the error, and this varies by method. For example the Delete() |
| 390 | * method comes with an ModelName and an Id. The List() method has only a ModelName. |
| 391 | * |
| 392 | * Stubs (RpcErrorWithModelNameToCordError) are provided below to make common usage more convenient. |
| 393 | */ |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 394 | |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 395 | func RpcErrorWithObjToCordError(err error, obj ObjectReference) error { |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 396 | if err == nil { |
| 397 | return err |
| 398 | } |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 399 | |
| 400 | st, ok := status.FromError(err) |
| 401 | if ok { |
| 402 | switch st.Code().String() { |
| 403 | case "PermissionDenied": |
| 404 | cordErr := &PermissionDeniedError{} |
| 405 | cordErr.Obj = obj |
| 406 | cordErr.Encapsulated = err |
| 407 | cordErr.AddStackTrace(2) |
| 408 | return cordErr |
| 409 | case "NotFound": |
| 410 | cordErr := &ModelNotFoundError{} |
| 411 | cordErr.Obj = obj |
| 412 | cordErr.Encapsulated = err |
| 413 | cordErr.AddStackTrace(2) |
| 414 | return cordErr |
Scott Baker | ce11c49 | 2019-07-30 15:53:34 -0700 | [diff] [blame] | 415 | case "Unavailable": |
| 416 | cordErr := &UnavailableError{} |
| 417 | cordErr.Obj = obj |
| 418 | cordErr.Encapsulated = err |
| 419 | cordErr.AddStackTrace(2) |
| 420 | return cordErr |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 421 | case "Unknown": |
| 422 | msg := st.Message() |
| 423 | if strings.HasPrefix(msg, "Exception calling application: ") { |
| 424 | msg = msg[31:] |
| 425 | } |
| 426 | cordErr := &InternalError{Message: msg} |
| 427 | cordErr.Obj = obj |
| 428 | cordErr.Encapsulated = err |
| 429 | cordErr.AddStackTrace(2) |
| 430 | return cordErr |
| 431 | } |
Scott Baker | ce11c49 | 2019-07-30 15:53:34 -0700 | [diff] [blame] | 432 | // Errors encapsulated by grpCurl |
| 433 | } else if strings.Contains(err.Error(), "failed to query for service descriptor") && |
| 434 | strings.Contains(err.Error(), "Unavailable") { |
| 435 | cordErr := &UnavailableError{} |
| 436 | cordErr.Obj = obj |
| 437 | cordErr.Encapsulated = err |
| 438 | cordErr.AddStackTrace(2) |
| 439 | return cordErr |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 440 | } |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 441 | |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 442 | return err |
| 443 | } |
| 444 | |
Scott Baker | a55e645 | 2019-06-25 11:10:30 -0700 | [diff] [blame] | 445 | func RpcErrorToCordError(err error) error { |
| 446 | return RpcErrorWithObjToCordError(err, ObjectReference{}) |
| 447 | } |
| 448 | |
| 449 | func RpcErrorWithModelNameToCordError(err error, modelName string) error { |
| 450 | return RpcErrorWithObjToCordError(err, ObjectReference{ModelName: modelName}) |
| 451 | } |
| 452 | |
| 453 | func RpcErrorWithIdToCordError(err error, modelName string, id int32) error { |
| 454 | return RpcErrorWithObjToCordError(err, ObjectReference{ModelName: modelName, Id: id}) |
| 455 | } |
| 456 | |
| 457 | func RpcErrorWithQueriesToCordError(err error, modelName string, queries map[string]string) error { |
| 458 | return RpcErrorWithObjToCordError(err, ObjectReference{ModelName: modelName, Queries: queries}) |
Scott Baker | 20481aa | 2019-06-20 11:00:54 -0700 | [diff] [blame] | 459 | } |