cubefs

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
	//
37
	// The gRPC framework will generate this error code when cancellation
38
	// is requested.
39
	Canceled Code = 1
40

41
	// Unknown error. An example of where this error may be returned is
42
	// if a Status value received from another address space belongs to
43
	// an error-space that is not known in this address space. Also
44
	// errors raised by APIs that do not return enough error information
45
	// may be converted to this error.
46
	//
47
	// The gRPC framework will generate this error code in the above two
48
	// mentioned cases.
49
	Unknown Code = 2
50

51
	// InvalidArgument indicates client specified an invalid argument.
52
	// Note that this differs from FailedPrecondition. It indicates arguments
53
	// that are problematic regardless of the state of the system
54
	// (e.g., a malformed file name).
55
	//
56
	// This error code will not be generated by the gRPC framework.
57
	InvalidArgument Code = 3
58

59
	// DeadlineExceeded means operation expired before completion.
60
	// For operations that change the state of the system, this error may be
61
	// returned even if the operation has completed successfully. For
62
	// example, a successful response from a server could have been delayed
63
	// long enough for the deadline to expire.
64
	//
65
	// The gRPC framework will generate this error code when the deadline is
66
	// exceeded.
67
	DeadlineExceeded Code = 4
68

69
	// NotFound means some requested entity (e.g., file or directory) was
70
	// not found.
71
	//
72
	// This error code will not be generated by the gRPC framework.
73
	NotFound Code = 5
74

75
	// AlreadyExists means an attempt to create an entity failed because one
76
	// already exists.
77
	//
78
	// This error code will not be generated by the gRPC framework.
79
	AlreadyExists Code = 6
80

81
	// PermissionDenied indicates the caller does not have permission to
82
	// execute the specified operation. It must not be used for rejections
83
	// caused by exhausting some resource (use ResourceExhausted
84
	// instead for those errors). It must not be
85
	// used if the caller cannot be identified (use Unauthenticated
86
	// instead for those errors).
87
	//
88
	// This error code will not be generated by the gRPC core framework,
89
	// but expect authentication middleware to use it.
90
	PermissionDenied Code = 7
91

92
	// ResourceExhausted indicates some resource has been exhausted, perhaps
93
	// a per-user quota, or perhaps the entire file system is out of space.
94
	//
95
	// This error code will be generated by the gRPC framework in
96
	// out-of-memory and server overload situations, or when a message is
97
	// larger than the configured maximum size.
98
	ResourceExhausted Code = 8
99

100
	// FailedPrecondition indicates operation was rejected because the
101
	// system is not in a state required for the operation's execution.
102
	// For example, directory to be deleted may be non-empty, an rmdir
103
	// operation is applied to a non-directory, etc.
104
	//
105
	// A litmus test that may help a service implementor in deciding
106
	// between FailedPrecondition, Aborted, and Unavailable:
107
	//  (a) Use Unavailable if the client can retry just the failing call.
108
	//  (b) Use Aborted if the client should retry at a higher-level
109
	//      (e.g., restarting a read-modify-write sequence).
110
	//  (c) Use FailedPrecondition if the client should not retry until
111
	//      the system state has been explicitly fixed. E.g., if an "rmdir"
112
	//      fails because the directory is non-empty, FailedPrecondition
113
	//      should be returned since the client should not retry unless
114
	//      they have first fixed up the directory by deleting files from it.
115
	//  (d) Use FailedPrecondition if the client performs conditional
116
	//      REST Get/Update/Delete on a resource and the resource on the
117
	//      server does not match the condition. E.g., conflicting
118
	//      read-modify-write on the same resource.
119
	//
120
	// This error code will not be generated by the gRPC framework.
121
	FailedPrecondition Code = 9
122

123
	// Aborted indicates the operation was aborted, typically due to a
124
	// concurrency issue like sequencer check failures, transaction aborts,
125
	// etc.
126
	//
127
	// See litmus test above for deciding between FailedPrecondition,
128
	// Aborted, and Unavailable.
129
	//
130
	// This error code will not be generated by the gRPC framework.
131
	Aborted Code = 10
132

133
	// OutOfRange means operation was attempted past the valid range.
134
	// E.g., seeking or reading past end of file.
135
	//
136
	// Unlike InvalidArgument, this error indicates a problem that may
137
	// be fixed if the system state changes. For example, a 32-bit file
138
	// system will generate InvalidArgument if asked to read at an
139
	// offset that is not in the range [0,2^32-1], but it will generate
140
	// OutOfRange if asked to read from an offset past the current
141
	// file size.
142
	//
143
	// There is a fair bit of overlap between FailedPrecondition and
144
	// OutOfRange. We recommend using OutOfRange (the more specific
145
	// error) when it applies so that callers who are iterating through
146
	// a space can easily look for an OutOfRange error to detect when
147
	// they are done.
148
	//
149
	// This error code will not be generated by the gRPC framework.
150
	OutOfRange Code = 11
151

152
	// Unimplemented indicates operation is not implemented or not
153
	// supported/enabled in this service.
154
	//
155
	// This error code will be generated by the gRPC framework. Most
156
	// commonly, you will see this error code when a method implementation
157
	// is missing on the server. It can also be generated for unknown
158
	// compression algorithms or a disagreement as to whether an RPC should
159
	// be streaming.
160
	Unimplemented Code = 12
161

162
	// Internal errors. Means some invariants expected by underlying
163
	// system has been broken. If you see one of these errors,
164
	// something is very broken.
165
	//
166
	// This error code will be generated by the gRPC framework in several
167
	// internal error conditions.
168
	Internal Code = 13
169

170
	// Unavailable indicates the service is currently unavailable.
171
	// This is a most likely a transient condition and may be corrected
172
	// by retrying with a backoff. Note that it is not always safe to retry
173
	// non-idempotent operations.
174
	//
175
	// See litmus test above for deciding between FailedPrecondition,
176
	// Aborted, and Unavailable.
177
	//
178
	// This error code will be generated by the gRPC framework during
179
	// abrupt shutdown of a server process or network connection.
180
	Unavailable Code = 14
181

182
	// DataLoss indicates unrecoverable data loss or corruption.
183
	//
184
	// This error code will not be generated by the gRPC framework.
185
	DataLoss Code = 15
186

187
	// Unauthenticated indicates the request does not have valid
188
	// authentication credentials for the operation.
189
	//
190
	// The gRPC framework will generate this error code when the
191
	// authentication metadata is invalid or a Credentials callback fails,
192
	// but also expect authentication middleware to generate it.
193
	Unauthenticated Code = 16
194

195
	_maxCode = 17
196
)
197

198
var strToCode = map[string]Code{
199
	`"OK"`: OK,
200
	`"CANCELLED"`:/* [sic] */ Canceled,
201
	`"UNKNOWN"`:             Unknown,
202
	`"INVALID_ARGUMENT"`:    InvalidArgument,
203
	`"DEADLINE_EXCEEDED"`:   DeadlineExceeded,
204
	`"NOT_FOUND"`:           NotFound,
205
	`"ALREADY_EXISTS"`:      AlreadyExists,
206
	`"PERMISSION_DENIED"`:   PermissionDenied,
207
	`"RESOURCE_EXHAUSTED"`:  ResourceExhausted,
208
	`"FAILED_PRECONDITION"`: FailedPrecondition,
209
	`"ABORTED"`:             Aborted,
210
	`"OUT_OF_RANGE"`:        OutOfRange,
211
	`"UNIMPLEMENTED"`:       Unimplemented,
212
	`"INTERNAL"`:            Internal,
213
	`"UNAVAILABLE"`:         Unavailable,
214
	`"DATA_LOSS"`:           DataLoss,
215
	`"UNAUTHENTICATED"`:     Unauthenticated,
216
}
217

218
// UnmarshalJSON unmarshals b into the Code.
219
func (c *Code) UnmarshalJSON(b []byte) error {
220
	// From json.Unmarshaler: By convention, to approximate the behavior of
221
	// Unmarshal itself, Unmarshalers implement UnmarshalJSON([]byte("null")) as
222
	// a no-op.
223
	if string(b) == "null" {
224
		return nil
225
	}
226
	if c == nil {
227
		return fmt.Errorf("nil receiver passed to UnmarshalJSON")
228
	}
229

230
	if ci, err := strconv.ParseUint(string(b), 10, 32); err == nil {
231
		if ci >= _maxCode {
232
			return fmt.Errorf("invalid code: %q", ci)
233
		}
234

235
		*c = Code(ci)
236
		return nil
237
	}
238

239
	if jc, ok := strToCode[string(b)]; ok {
240
		*c = jc
241
		return nil
242
	}
243
	return fmt.Errorf("invalid code: %q", string(b))
244
}
245