Dinesh Belwalkar | e63f7f9 | 2019-11-22 23:11:16 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * |
| 3 | * Copyright 2014 gRPC authors. |
| 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 | |
| 19 | // Package codes defines the canonical error codes used by gRPC. It is |
| 20 | // consistent across various languages. |
| 21 | package codes // import "google.golang.org/grpc/codes" |
| 22 | |
| 23 | import ( |
| 24 | "fmt" |
| 25 | "strconv" |
| 26 | ) |
| 27 | |
| 28 | // A Code is an unsigned 32-bit error code as defined in the gRPC spec. |
| 29 | type Code uint32 |
| 30 | |
| 31 | const ( |
| 32 | // OK is returned on success. |
| 33 | OK Code = 0 |
| 34 | |
| 35 | // Canceled indicates the operation was canceled (typically by the caller). |
| 36 | Canceled Code = 1 |
| 37 | |
| 38 | // Unknown error. An example of where this error may be returned is |
| 39 | // if a Status value received from another address space belongs to |
| 40 | // an error-space that is not known in this address space. Also |
| 41 | // errors raised by APIs that do not return enough error information |
| 42 | // may be converted to this error. |
| 43 | Unknown Code = 2 |
| 44 | |
| 45 | // InvalidArgument indicates client specified an invalid argument. |
| 46 | // Note that this differs from FailedPrecondition. It indicates arguments |
| 47 | // that are problematic regardless of the state of the system |
| 48 | // (e.g., a malformed file name). |
| 49 | InvalidArgument Code = 3 |
| 50 | |
| 51 | // DeadlineExceeded means operation expired before completion. |
| 52 | // For operations that change the state of the system, this error may be |
| 53 | // returned even if the operation has completed successfully. For |
| 54 | // example, a successful response from a server could have been delayed |
| 55 | // long enough for the deadline to expire. |
| 56 | DeadlineExceeded Code = 4 |
| 57 | |
| 58 | // NotFound means some requested entity (e.g., file or directory) was |
| 59 | // not found. |
| 60 | NotFound Code = 5 |
| 61 | |
| 62 | // AlreadyExists means an attempt to create an entity failed because one |
| 63 | // already exists. |
| 64 | AlreadyExists Code = 6 |
| 65 | |
| 66 | // PermissionDenied indicates the caller does not have permission to |
| 67 | // execute the specified operation. It must not be used for rejections |
| 68 | // caused by exhausting some resource (use ResourceExhausted |
| 69 | // instead for those errors). It must not be |
| 70 | // used if the caller cannot be identified (use Unauthenticated |
| 71 | // instead for those errors). |
| 72 | PermissionDenied Code = 7 |
| 73 | |
| 74 | // ResourceExhausted indicates some resource has been exhausted, perhaps |
| 75 | // a per-user quota, or perhaps the entire file system is out of space. |
| 76 | ResourceExhausted Code = 8 |
| 77 | |
| 78 | // FailedPrecondition indicates operation was rejected because the |
| 79 | // system is not in a state required for the operation's execution. |
| 80 | // For example, directory to be deleted may be non-empty, an rmdir |
| 81 | // operation is applied to a non-directory, etc. |
| 82 | // |
| 83 | // A litmus test that may help a service implementor in deciding |
| 84 | // between FailedPrecondition, Aborted, and Unavailable: |
| 85 | // (a) Use Unavailable if the client can retry just the failing call. |
| 86 | // (b) Use Aborted if the client should retry at a higher-level |
| 87 | // (e.g., restarting a read-modify-write sequence). |
| 88 | // (c) Use FailedPrecondition if the client should not retry until |
| 89 | // the system state has been explicitly fixed. E.g., if an "rmdir" |
| 90 | // fails because the directory is non-empty, FailedPrecondition |
| 91 | // should be returned since the client should not retry unless |
| 92 | // they have first fixed up the directory by deleting files from it. |
| 93 | // (d) Use FailedPrecondition if the client performs conditional |
| 94 | // REST Get/Update/Delete on a resource and the resource on the |
| 95 | // server does not match the condition. E.g., conflicting |
| 96 | // read-modify-write on the same resource. |
| 97 | FailedPrecondition Code = 9 |
| 98 | |
| 99 | // Aborted indicates the operation was aborted, typically due to a |
| 100 | // concurrency issue like sequencer check failures, transaction aborts, |
| 101 | // etc. |
| 102 | // |
| 103 | // See litmus test above for deciding between FailedPrecondition, |
| 104 | // Aborted, and Unavailable. |
| 105 | Aborted Code = 10 |
| 106 | |
| 107 | // OutOfRange means operation was attempted past the valid range. |
| 108 | // E.g., seeking or reading past end of file. |
| 109 | // |
| 110 | // Unlike InvalidArgument, this error indicates a problem that may |
| 111 | // be fixed if the system state changes. For example, a 32-bit file |
| 112 | // system will generate InvalidArgument if asked to read at an |
| 113 | // offset that is not in the range [0,2^32-1], but it will generate |
| 114 | // OutOfRange if asked to read from an offset past the current |
| 115 | // file size. |
| 116 | // |
| 117 | // There is a fair bit of overlap between FailedPrecondition and |
| 118 | // OutOfRange. We recommend using OutOfRange (the more specific |
| 119 | // error) when it applies so that callers who are iterating through |
| 120 | // a space can easily look for an OutOfRange error to detect when |
| 121 | // they are done. |
| 122 | OutOfRange Code = 11 |
| 123 | |
| 124 | // Unimplemented indicates operation is not implemented or not |
| 125 | // supported/enabled in this service. |
| 126 | Unimplemented Code = 12 |
| 127 | |
| 128 | // Internal errors. Means some invariants expected by underlying |
| 129 | // system has been broken. If you see one of these errors, |
| 130 | // something is very broken. |
| 131 | Internal Code = 13 |
| 132 | |
| 133 | // Unavailable indicates the service is currently unavailable. |
| 134 | // This is a most likely a transient condition and may be corrected |
| 135 | // by retrying with a backoff. Note that it is not always safe to retry |
| 136 | // non-idempotent operations. |
| 137 | // |
| 138 | // See litmus test above for deciding between FailedPrecondition, |
| 139 | // Aborted, and Unavailable. |
| 140 | Unavailable Code = 14 |
| 141 | |
| 142 | // DataLoss indicates unrecoverable data loss or corruption. |
| 143 | DataLoss Code = 15 |
| 144 | |
| 145 | // Unauthenticated indicates the request does not have valid |
| 146 | // authentication credentials for the operation. |
| 147 | Unauthenticated Code = 16 |
| 148 | |
| 149 | _maxCode = 17 |
| 150 | ) |
| 151 | |
| 152 | var strToCode = map[string]Code{ |
| 153 | `"OK"`: OK, |
| 154 | `"CANCELLED"`:/* [sic] */ Canceled, |
| 155 | `"UNKNOWN"`: Unknown, |
| 156 | `"INVALID_ARGUMENT"`: InvalidArgument, |
| 157 | `"DEADLINE_EXCEEDED"`: DeadlineExceeded, |
| 158 | `"NOT_FOUND"`: NotFound, |
| 159 | `"ALREADY_EXISTS"`: AlreadyExists, |
| 160 | `"PERMISSION_DENIED"`: PermissionDenied, |
| 161 | `"RESOURCE_EXHAUSTED"`: ResourceExhausted, |
| 162 | `"FAILED_PRECONDITION"`: FailedPrecondition, |
| 163 | `"ABORTED"`: Aborted, |
| 164 | `"OUT_OF_RANGE"`: OutOfRange, |
| 165 | `"UNIMPLEMENTED"`: Unimplemented, |
| 166 | `"INTERNAL"`: Internal, |
| 167 | `"UNAVAILABLE"`: Unavailable, |
| 168 | `"DATA_LOSS"`: DataLoss, |
| 169 | `"UNAUTHENTICATED"`: Unauthenticated, |
| 170 | } |
| 171 | |
| 172 | // UnmarshalJSON unmarshals b into the Code. |
| 173 | func (c *Code) UnmarshalJSON(b []byte) error { |
| 174 | // From json.Unmarshaler: By convention, to approximate the behavior of |
| 175 | // Unmarshal itself, Unmarshalers implement UnmarshalJSON([]byte("null")) as |
| 176 | // a no-op. |
| 177 | if string(b) == "null" { |
| 178 | return nil |
| 179 | } |
| 180 | if c == nil { |
| 181 | return fmt.Errorf("nil receiver passed to UnmarshalJSON") |
| 182 | } |
| 183 | |
| 184 | if ci, err := strconv.ParseUint(string(b), 10, 32); err == nil { |
| 185 | if ci >= _maxCode { |
| 186 | return fmt.Errorf("invalid code: %q", ci) |
| 187 | } |
| 188 | |
| 189 | *c = Code(ci) |
| 190 | return nil |
| 191 | } |
| 192 | |
| 193 | if jc, ok := strToCode[string(b)]; ok { |
| 194 | *c = jc |
| 195 | return nil |
| 196 | } |
| 197 | return fmt.Errorf("invalid code: %q", string(b)) |
| 198 | } |