Merge pull request PelicanPlatform#949 from joereuss12/enum-client-er…

…ror-codes-branch

First draft of enum client error codes

client/handle_http.go

@@ -53,6 +53,7 @@ import (
 	"golang.org/x/time/rate"
 
 	"github.com/pelicanplatform/pelican/config"
+	"github.com/pelicanplatform/pelican/error_codes"
 	"github.com/pelicanplatform/pelican/namespaces"
 	"github.com/pelicanplatform/pelican/param"
 )
@@ -85,6 +86,8 @@ var (
 			return item
 		},
 	)
+
+	PelicanError error_codes.PelicanError
 )
 
 type (
@@ -1969,6 +1972,7 @@ Loop:
 					Duration:         resp.Duration(),
 					BytesTotal:       totalSize,
 				}
+				err = error_codes.NewTransfer_SlowTransferError(err)
 				return
 
 			} else {

client/handle_http_test.go

@@ -42,6 +42,7 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"github.com/pelicanplatform/pelican/config"
+	"github.com/pelicanplatform/pelican/error_codes"
 	"github.com/pelicanplatform/pelican/mock"
 	"github.com/pelicanplatform/pelican/namespaces"
 	"github.com/pelicanplatform/pelican/test_utils"
@@ -227,7 +228,16 @@ func TestSlowTransfers(t *testing.T) {
 
 	// Make sure the errors are correct
 	assert.NotNil(t, err)
-	assert.IsType(t, &SlowTransferError{}, err)
+	// Check we have an overlapping PelicanError type
+	_, ok := err.(*error_codes.PelicanError)
+	if ok {
+		var slowTransferError *SlowTransferError
+		assert.Contains(t, err.Error(), "Transfer.SlowTransfer Error: Error code 6002:")
+		// Check we successfully wrapped an already defined SlowTransferError
+		assert.True(t, errors.As(err, &slowTransferError))
+	} else {
+		t.Fatal("Error is not of type PelicanError")
+	}
 }
 
 // Test stopped transfer

cmd/object_get.go

@@ -24,6 +24,7 @@ import (
 
 	"github.com/pelicanplatform/pelican/client"
 	"github.com/pelicanplatform/pelican/config"
+	"github.com/pelicanplatform/pelican/error_codes"
 	"github.com/pelicanplatform/pelican/param"
 	"github.com/pelicanplatform/pelican/utils"
 	"github.com/pkg/errors"
@@ -131,15 +132,22 @@ func getMain(cmd *cobra.Command, args []string) {
 	if result != nil {
 		// Print the list of errors
 		errMsg := result.Error()
+		var pe error_codes.PelicanError
 		var te *client.TransferErrors
 		if errors.As(result, &te) {
 			errMsg = te.UserError()
 		}
-		log.Errorln("Failure getting " + lastSrc + ": " + errMsg)
-		if client.ShouldRetry(result) {
-			log.Errorln("Errors are retryable")
-			os.Exit(11)
+		if errors.Is(result, &pe) {
+			errMsg = pe.Error()
+			log.Errorln("Failure getting " + lastSrc + ": " + errMsg)
+			os.Exit(pe.ExitCode())
+		} else { // For now, keeping this else here to catch any errors that are not classified PelicanErrors
+			log.Errorln("Failure getting " + lastSrc + ": " + errMsg)
+			if client.ShouldRetry(result) {
+				log.Errorln("Errors are retryable")
+				os.Exit(11)
+			}
+			os.Exit(1)
 		}
-		os.Exit(1)
 	}
 }

docs/error_codes.yaml

@@ -0,0 +1,162 @@
+#
+# Copyright (C) 2024, Pelican Project, Morgridge Institute for Research
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you
+# may not use this file except in compliance with the License.  You may
+# obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# This file contains structured documentation about the Pelican parameters.
+# While it is somewhat human-readable, it is meant to help with the documentation
+# generation.
+
+############################
+#    Client Error Codes    #
+############################
+
+# The below client error codes are 4 digits and each digit has a specific meaning:
+# 1st digit: The type of error
+# 2nd digit: Nothing yet
+# 3rd digit: Represents if the user/submitter can do a modification to fix the error (1 if it is at user's fault, 0 otherwise)
+# 4th digit: The sub-type of the error
+
+# The clientExitCode is the code that is used to exit the client process
+
+# Retryable is a boolean value that indicates if the error could be solved with a HTCondor job retry.
+# This means that the whole client process will restart with the HTCondor job so the process could succeed
+# if it hits a different cache/site or hits the same cache/site when it is in a better state.
+
+############################
+#     Parameter Errors     #
+############################
+---
+type: Parameter
+code: 1000
+clientExitCode: 4
+description: >-
+  If the client failed to start, or was started with invalid parameters, or otherwise believes what it
+  was asked to do is impossible or the request itself is malformed.
+retryable: false
+
+############################
+#    Resolution Errors     #
+############################
+---
+type: Resolution
+code: 2000
+clientExitCode: 5
+description: >-
+  Indicates that the client failed to even attempt to contact the server.
+retryable: false
+
+############################
+#      Contact Errors      #
+############################
+---
+type: Contact
+code: 3000
+clientExitCode: 6
+description: >-
+  The client attempted to contact the server at its resolved address and failed to do so.
+retryable: false
+---
+type: Contact.Director
+code: 3001
+clientExitCode: 6
+description: >-
+  The client attempted to contact the director at its found address but failed to do so.
+retryable: false
+---
+type: Contact.Cache
+code: 3002
+clientExitCode: 11
+description: >-
+  The client attempted to contact the cache but failed to do so.
+retryable: true
+---
+type: Contact.Origin
+code: 3003
+clientExitCode: 6
+description: >-
+  The client attempted to contact the origin but failed to do so.
+retryable: false
+---
+type: Contact.Registry
+code: 3004
+clientExitCode: 6
+description: >-
+  The client attempted to contact the registry (usually through the director) but failed to do so.
+retryable: false
+
+############################
+#   Authorization Errors   #
+############################
+---
+type: Authorization
+code: 4000
+clientExitCode: 7
+description: >-
+  The client contacted the server but failed to authenticate, or failed to authorize, or if
+  the server replied with an authorization error when the file was requested or sent.
+retryable: false
+
+############################
+#   Specification Errors   #
+############################
+---
+type: Specification
+code: 5000
+clientExitCode: 8
+description: >-
+  If the client successfully contacted the server and received a definitive response that the
+  desired file was not present or could not be created. Usually the submitters fault.
+retryable: false
+---
+type: Specification.FileNotFound
+code: 5011
+clientExitCode: 8
+description: >-
+  If the client successfully contacted the server but the desired file does not exist for download.
+  The user might have enterred the wrong URL or the file might not yet be at the specified origin.
+retryable: false
+---
+type: Specification.FileNotCreated
+code: 5002
+clientExitCode: 8
+description: >-
+  If the client successfully contacted the server but the desired file for upload could not be created.
+retryable: false
+
+############################
+#     Transfer Errors      #
+############################
+---
+type: Transfer
+code: 6000
+clientExitCode: 9
+description: >-
+  The client started transferring the file but did not complete it for some reason, or if the file
+  failed post-transfer validation.
+retryable: true
+---
+type: Transfer.StoppedTransfer
+code: 6001
+clientExitCode: 11
+description: >-
+  The client started transferring file(s) but it got cancelled by Pelican as stopped transferring data.
+retryable: true
+---
+type: Transfer.SlowTransfer
+code: 6002
+clientExitCode: 11
+description: >-
+  The client started transferring data but the transfer was slower than the minumum configured timeout rate.
+retryable: true