package xerrors

// Code is the machine-readable error category.
// Wire values are stable across versions and are identical to gRPC status code
// names. HTTP mapping is the responsibility of the transport layer, not this package.
type Code string

const (
	// ErrInvalidInput indicates the request contains malformed or invalid data.
	// HTTP 400 / gRPC INVALID_ARGUMENT.
	ErrInvalidInput Code = "INVALID_ARGUMENT"

	// ErrOutOfRange indicates a parameter or index exceeds the valid bounds.
	// Use when the value itself is well-formed but falls outside accepted limits
	// (e.g. page number past the last page, offset past end of file).
	// HTTP 400 / gRPC OUT_OF_RANGE.
	ErrOutOfRange Code = "OUT_OF_RANGE"

	// ErrUnauthorized indicates the request lacks valid authentication credentials.
	// HTTP 401 / gRPC UNAUTHENTICATED.
	ErrUnauthorized Code = "UNAUTHENTICATED"

	// ErrPermissionDenied indicates the authenticated caller lacks permission for
	// the operation. Authentication is not the issue.
	// HTTP 403 / gRPC PERMISSION_DENIED.
	ErrPermissionDenied Code = "PERMISSION_DENIED"

	// ErrNotFound indicates the requested resource does not exist.
	// HTTP 404 / gRPC NOT_FOUND.
	ErrNotFound Code = "NOT_FOUND"

	// ErrAlreadyExists indicates a resource with the same identifier already exists.
	// Use for creation conflicts (e.g. duplicate email on sign-up).
	// HTTP 409 / gRPC ALREADY_EXISTS.
	ErrAlreadyExists Code = "ALREADY_EXISTS"

	// ErrAborted indicates the operation was aborted due to a concurrent modification
	// or transaction conflict. Unlike ErrAlreadyExists (creation conflict) and
	// ErrPreconditionFailed (business rule), this signals the caller may retry.
	// HTTP 409 / gRPC ABORTED.
	ErrAborted Code = "ABORTED"

	// ErrGone indicates the resource existed but has been permanently removed.
	// Unlike ErrNotFound, this signals the caller should not retry.
	// HTTP 410 / non-standard gRPC extension.
	ErrGone Code = "GONE"

	// ErrPreconditionFailed indicates a required business condition was not met.
	// The input is valid but a rule blocks the action (e.g. "cannot delete an
	// account with active subscriptions").
	// HTTP 412 / gRPC FAILED_PRECONDITION.
	ErrPreconditionFailed Code = "FAILED_PRECONDITION"

	// ErrRateLimited indicates the caller has exceeded a rate limit or quota.
	// HTTP 429 / gRPC RESOURCE_EXHAUSTED.
	ErrRateLimited Code = "RESOURCE_EXHAUSTED"

	// ErrCancelled indicates the operation was cancelled by the caller.
	// HTTP 499 / gRPC CANCELLED.
	ErrCancelled Code = "CANCELLED"

	// ErrInternal indicates an unexpected server-side failure.
	// Use a more specific code when one applies.
	// HTTP 500 / gRPC INTERNAL.
	ErrInternal Code = "INTERNAL"

	// ErrDataLoss indicates unrecoverable data loss or corruption.
	// Reserved for storage-layer integrity failures.
	// HTTP 500 / gRPC DATA_LOSS.
	ErrDataLoss Code = "DATA_LOSS"

	// ErrNotImplemented indicates the requested operation has not been implemented.
	// HTTP 501 / gRPC UNIMPLEMENTED.
	ErrNotImplemented Code = "UNIMPLEMENTED"

	// ErrUnavailable indicates the service is temporarily unable to handle requests.
	// HTTP 503 / gRPC UNAVAILABLE.
	ErrUnavailable Code = "UNAVAILABLE"

	// ErrDeadlineExceeded indicates the operation timed out before completing.
	// HTTP 504 / gRPC DEADLINE_EXCEEDED.
	ErrDeadlineExceeded Code = "DEADLINE_EXCEEDED"
)

// Description returns a human-readable description for the code.
// Unknown codes return their raw string value.
func (c Code) Description() string {
	switch c {
	case ErrInvalidInput:
		return "Invalid input provided"
	case ErrOutOfRange:
		return "Value out of valid range"
	case ErrUnauthorized:
		return "Authentication required"
	case ErrPermissionDenied:
		return "Insufficient permissions"
	case ErrNotFound:
		return "Resource not found"
	case ErrAlreadyExists:
		return "Resource already exists"
	case ErrAborted:
		return "Operation aborted due to concurrent modification"
	case ErrGone:
		return "Resource permanently deleted"
	case ErrPreconditionFailed:
		return "Precondition not met"
	case ErrRateLimited:
		return "Rate limit exceeded"
	case ErrCancelled:
		return "Request cancelled"
	case ErrInternal:
		return "Internal error"
	case ErrDataLoss:
		return "Unrecoverable data loss or corruption"
	case ErrNotImplemented:
		return "Not implemented"
	case ErrUnavailable:
		return "Service unavailable"
	case ErrDeadlineExceeded:
		return "Deadline exceeded"
	default:
		return string(c)
	}
}